# Cold Email Integration

## When to use

Use this skill when a task requires reading or writing cold outbound email data in the Cold Email app: creating or updating leads and lead lists, inspecting or building outbound campaigns and sequence steps, enrolling or unenrolling leads in a campaign, or pausing/resuming a campaign. Do not use it for transactional or marketing email delivery — that belongs to a different app.

## Tools

- `http-get` — read leads, lead lists, campaigns, and the authenticated workspace
- `http-post` — create leads, lead lists, campaigns, bulk-import leads, and enroll leads/lead lists into a campaign
- `http-request` — update or delete leads, update campaigns (including pause/resume via `status`), and unenroll a lead from a campaign
- `write-file` — stage large result sets (lead lists, paginated lead exports, campaign rosters) instead of holding them in context
- `send-message` — escalate to a human when authentication fails or the integration is missing

All calls target the base URL configured in the org's Integration row for the Cold Email app (for example `https://coldemail.newx.app/api/v1/...`). Authentication is injected automatically by the Integration row — never ask for, echo, or hardcode credentials. Optionally include `X-Workspace: <slug>` to assert the expected workspace.

## Playbook

1. Call `http-get` on `/api/v1/workspace` first to confirm the authenticated workspace before doing anything else. Treat this as the canonical who-am-I check.
2. To find existing leads or check for duplicates, call `http-get` on `/api/v1/leads`, optionally filtering by `lead_list_id`. Use `http-get` on `/api/v1/leads/:id` for a single lead's detail.
3. To add a single new lead, call `http-post` on `/api/v1/leads`. For bulk additions (e.g. importing a prospect list), call `http-post` on `/api/v1/leads/import` with a `rows[]` payload; this endpoint applies dedup and suppression filtering automatically and accepts `update_existing` to upsert.
4. To modify or remove a lead, call `http-request` (PATCH) on `/api/v1/leads/:id` or `http-request` (DELETE) on `/api/v1/leads/:id`.
5. To organize leads, call `http-get` on `/api/v1/lead_lists` to list existing lists, or `http-post` on `/api/v1/lead_lists` to create a new one before importing leads into it.
6. To inspect outbound sequences, call `http-get` on `/api/v1/campaigns` for the list, or `http-get` on `/api/v1/campaigns/:id` for full sequence steps and variants of one campaign.
7. To build a new outbound sequence, call `http-post` on `/api/v1/campaigns` with the nested steps/variants payload describing each touch in the sequence.
8. To pause or resume a campaign, or change any campaign attribute, call `http-request` (PATCH) on `/api/v1/campaigns/:id`, setting `status` accordingly.
9. To start sending to leads, call `http-post` on `/api/v1/campaigns/:campaign_id/enrollments` with the leads and/or lead lists to enroll.
10. To stop sending to a specific lead, call `http-request` (DELETE) on `/api/v1/campaigns/:campaign_id/enrollments/:id`; this cancels that lead's pending sequence steps without touching the rest of the campaign.
11. When a result set is large (a full lead export, a large campaign roster, or a bulk import response), use `write-file` to stage it rather than inlining it in the conversation.

## Failure modes

If any call returns 401 or 403, or the org has no Integration row configured for Cold Email, stop immediately — do not retry with guessed credentials or alternate endpoints. Use `send-message` to escalate to a human, naming the Cold Email app and the specific scopes needed (e.g. leads read/write, campaigns read/write). A 404 on a resource you expect to exist may mean it belongs to another workspace; do not attempt to work around this — cross-tenant access is intentionally indistinguishable from a missing resource.

## Done when

The requested leads, lead lists, or campaigns exist or are updated as specified and confirmed via a follow-up `http-get`, enrollments/unenrollments have been applied and reflected in the campaign or lead state, and any large result set has been staged with `write-file`. If the task could not be completed due to authentication or missing integration, it is done when the escalation has been sent via `send-message`.