Leads & campaigns.
Every lead-ingest route and the full campaign lifecycle, field by field. All routes below require Authorization: Bearer $WARMHAWK_KEY except POST /v1/leads/webhook, which is deliberately public.
Three lead-ingest paths (single create, CSV import, unauthenticated webhook) share one validation function and an open customFields object; DELETE /v1/leads/erase handles GDPR erasure. Campaigns are created with a template (spintax-capable fallback body) and an aiPromptTemplate (mustache-placeholder AI instructions). Each campaign picks the mailboxes it sends from (mailboxIds) and can carry up to three follow-ups (steps). unsubscribeUrlTemplate is optional: without it every email links to the built-in unsubscribe page. An optional send schedule limits sending to set days and hours in one time zone (or each lead’s). Launch is gated on picked senders, a mailing address on every sending domain, a working unsubscribe link, non-empty copy, merge fields every lead can fill and the bounce circuit breaker. The blocked list (/v1/suppression) can be searched, imported, exported and unblocked.
Leads
| Route | What it does |
|---|---|
| GET /v1/leads?campaignId= | List leads, optionally scoped to a campaign. Also takes status, q (searches email, name and company; % and _ match as plain text), sort (name, email, company, campaign, status, added) and dir. Returns { leads, total, statusCounts }. |
| POST /v1/leads | Single-lead create. Body: campaignId, email, firstName?, lastName?, company?, customFields?. 201, or 409 on suppressed/duplicate. |
| POST /v1/leads/webhook | Unauthenticated ingest webhook — no bearer token. Rate-limited (30/min). Skips (200) rather than errors on suppressed/duplicate. |
| POST /v1/leads/import | Bulk CSV import — multipart/form-data, fields: campaignId, file. Caps: 50,000 rows / 10MB. |
| PATCH /v1/leads/:id | Edit email, firstName, lastName, company or customFields before the lead is emailed. Only an UNTOUCHED lead changes (409 after that); 409 on a blocked or duplicate address, 422 on bad fields. Keeps its place in the send order. |
| POST /v1/leads/:id/suppress | Manually suppress a lead (adds to the suppression list, flips status). |
| DELETE /v1/leads/erase | GDPR erasure by email. Body: { email }. Anonymizes PII across every campaign, preserves aggregate counts. |
| DELETE /v1/leads/:id | Hard delete one lead row by id. 204, or 404 if not found. |
| GET /v1/suppression?q=&page= | The blocked list, newest first. Returns { entries, total, page, pageSize }. |
| POST /v1/suppression/import | Body: { emails } (up to 10,000). Returns { added, alreadyBlocked, invalid }. 422 when empty. |
| GET /v1/suppression/export | Every blocked address: { entries: [{ email, source, reason, createdAt }] }. |
| POST /v1/suppression/unblock | Body: { email }. Returns { email, unblocked: true }, or 404 if the address isn’t blocked. |
API details (Tier 0 / self-hosters) · POST /v1/leads/import — multipart, not JSON▸
curl -X POST https://your-instance/v1/leads/import \
-H "Authorization: Bearer $WARMHAWK_KEY" \
-F "campaignId=camp_g7h8i9" \
-F "file=@leads.csv"Full walkthrough with request/response bodies for every lead route: Leads & enrichment.
Campaigns
| Route | What it does |
|---|---|
| GET /v1/campaigns | List campaigns, including mailboxIds, steps, senders (each ticked mailbox and whether its domain has an address), sendWindow, launch { canLaunch, problems }, progress (with followUpsSent, upcomingFollowUps and nextSendAt), aiWrittenCount/aiFallbackCount and leadsCount/sentCount/repliesCount/domainsCount/lastActivityAt. |
| GET /v1/campaigns/:id | Fetch one campaign, with mailboxIds and steps. 404 if not found. |
| GET /v1/campaigns/:id/launch-check | The launch check without launching. Returns { canLaunch, problems, warnings, passed }. |
| POST /v1/campaigns | Create. Body: name, aiPromptTemplate, template?, subject?, aiProvider?, aiMode? (PERSONALIZE or PROMPT), aiWritesSubject?, unsubscribeUrlTemplate?, mailboxIds?, steps?, and the schedule fields sendTimezone?, sendDays?, sendStartMinute?, sendEndMinute?, useLeadTimezone?, maxNewLeadsPerDay?. Returns the row plus contentQuality. |
| PATCH /v1/campaigns/:id | Update content and AI fields, the schedule fields, bounceRateThreshold, pausedForBounceRate, mailboxIds or steps. Schedule fields merge with the saved ones; sendTimezone: null clears the schedule. mailboxIds and steps each replace the whole list. status is refused (422): use launch or pause. Recomputes contentQuality when template or subject changes. |
| POST /v1/campaigns/:id/launch | Runs the launch check and sets status: ACTIVE. Otherwise 422 with every problem at once: NO_SENDERS, DOMAIN_NO_ADDRESS (one per domain), NO_UNSUBSCRIBE, BOUNCE_PAUSED, EMAIL_EMPTY, STEP_EMPTY, FIELD_UNKNOWN (a {{field}} no lead has), FIELD_BLANK (a field with no fallback that some leads leave blank). Warnings (SENDER_NAME_MISSING, ALL_WARMING, NO_LEADS) never block. A campaign with nothing left to send moves to COMPLETED on its own. |
| POST /v1/campaigns/preview | One email exactly as a lead gets it, footer included. Body: campaignId? plus any draft fields to layer over the saved ones, leadIndex? (0–2) or leadId? (one of the campaign’s leads, sent from its own mailbox), step? (0 = first email, 1–3 = a follow-up), skipAi? (your text, no AI call). With AI on, makes one call on your key; usesAi in the response says whether AI writes it at send time. Nothing is stored. |
| POST /v1/campaigns/:id/test-send | Sends one [Test] email to { to, step?, leadIndex? } from the first ticked mailbox. Returns { status, to, from, messageId, aiOutcome, aiFallbackReason }. Its unsubscribe link blocks nobody. 422 without a mailbox, address or unsubscribe link; 502 with the mail server’s reason. |
| POST /v1/campaigns/:id/duplicate | A new DRAFT named “Copy of …” with the same email, follow-ups, AI settings, unsubscribe link, schedule and senders. Leads, replies and history stay with the original. 201. |
| POST /v1/campaigns/:id/pause | Sets status: PAUSED. |
| DELETE /v1/campaigns/:id | Archives (status: ARCHIVED) — does not hard-delete. |
API details (Tier 0 / self-hosters) · POST /v1/campaigns — request body▸
{
"name": "Q3 outbound — agencies",
"template": "Hi there — {quick question|one question} for you today?",
"aiPromptTemplate": "Write a 2-sentence opener to {{firstName}} at {{company}}.",
"aiProvider": "GEMINI",
"aiMode": "PERSONALIZE",
"unsubscribeUrlTemplate": "https://yourcompany.com/unsubscribe?email={{email}}",
"mailboxIds": ["mbx_a1b2c3", "mbx_d4e5f6"],
"steps": [
{ "waitDays": 3, "body": "Just floating this back up — worth a look?", "aiRewrite": false },
{ "waitDays": 4, "body": "Last note from me on this one.", "aiRewrite": false }
],
"sendTimezone": "America/Chicago",
"sendDays": [1, 2, 3, 4, 5],
"sendStartMinute": 540,
"sendEndMinute": 1020,
"maxNewLeadsPerDay": 50
}API details (Tier 0 / self-hosters) · POST /v1/campaigns/:id/launch — 422 when it can't launch yet▸
{
"error": "acme.com has no mailing address; Follow-up 2 needs backup text",
"problems": [
{ "code": "DOMAIN_NO_ADDRESS", "message": "acme.com has no mailing address",
"domainId": "dom_a1b2c3", "domainName": "acme.com", "mailboxCount": 2 },
{ "code": "STEP_EMPTY", "message": "Follow-up 2 needs backup text", "position": 2 }
],
"warnings": []
}Full field reference, spintax syntax, and the AI personalization mechanics: Campaigns, AI & content quality.
Back to Auth & mailboxes, or continue to Queue, domains & webhooks.