# Email Marketing Integration

## When to use

Use this skill whenever a task requires provisioning a contact or lead as a user account inside the Email Marketing app before it can receive campaigns, sequences, or transactional messages. Typical triggers: a new lead closes and needs to be enrolled in a nurture sequence, a signup event needs a corresponding Email Marketing account, or another workflow step asks you to "make sure this email exists in Email Marketing" before continuing.

## Tools

This skill uses `http-get`, `http-post`, `http-request`, `write-file`, and `send-message`.

## Playbook

1. Confirm you have a single, valid email address to provision. If the input contains multiple emails or an ambiguous identity, resolve to one canonical email before calling the API; if you cannot resolve it, use `send-message` to escalate to a human rather than guessing.
2. Provision (or idempotently fetch) the account using `http-post` against `/api/v1/accounts`, sending the email address in the request body. This endpoint is idempotent — calling it again with the same email returns the existing account rather than creating a duplicate, so it is always safe to call before enrolling someone in a campaign.
3. Read the JSON response and confirm it contains `id`, `email`, and `status`. Treat the returned `id` as the durable reference for this contact within Email Marketing — use it (not the raw email string) in any follow-up steps or messages to other tools/agents in the same workflow.
4. If the task involves a batch of contacts (for example, a CSV of leads), loop step 2 for each email one at a time. If the batch is large, use `write-file` to stage the full set of resulting `{id, email, status}` records to a result file before reporting back, rather than inlining hundreds of records into a message.
5. If `status` on the returned account indicates the contact is unsubscribed or suppressed, do not treat provisioning as a failure — record the status faithfully and let the calling workflow decide whether to proceed with enrollment. Provisioning and consent are separate concerns.
6. Once all required accounts are provisioned, report back the account id(s) and status(es) obtained so the calling workflow can proceed (e.g., add to a sequence, tag, or campaign) in whatever step comes next.

Only `POST /api/v1/accounts` is confirmed for this integration. Do not invent read, update, or delete endpoints, tagging endpoints, or campaign-enrollment endpoints — if a task requires functionality beyond provisioning an account, stop and use `send-message` to escalate, naming the specific capability that is missing.

## Failure modes

- 401 or 403 response: stop immediately. Use `send-message` to escalate to a human, naming "Email Marketing" as the app and stating that the "write" scope is required for `/api/v1/accounts`. Do not retry with different credentials and never ask the user for a token.
- Missing or unconfigured Integration row for Email Marketing in the org: stop and use `send-message` to escalate, naming "Email Marketing" as the app that needs to be connected.
- Malformed or missing email address in the input: do not call the API with a guessed or partial value; use `send-message` to escalate and request clarification.
- Network or 5xx error from the endpoint: retry once; if it fails again, use `send-message` to escalate, including the endpoint path and status code observed.

## Done when

Every required contact has a confirmed Email Marketing account, evidenced by a successful response from `/api/v1/accounts` containing `id`, `email`, and `status` for each one, and — for batches — a staged result file (via `write-file`) has been produced when the caller needs the full list rather than a single record.