Cold Email Integration

skill

Read, create, and update Cold Email records through its REST API using an org Integration row.

Download .md

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.