Two content fields, one job each.
A campaign ties a message to a send policy. Content quality (spam score, spintax validity) is evaluated on every save, not just before send — so you see the signal while you’re still writing, not after launch.
A WarmHawk campaign has two content fields: template (the literal fallback body, supports native spintax variation) and aiPromptTemplate (instructions for your BYOK Gemini/Claude key, supports flat {{fieldName}} placeholders). Every create/update computes a contentQuality block — spam-word score plus spintax group count. A campaign sends only from the mailboxes it picks, can add up to three follow-ups in the same thread, can be limited to set days and hours in a time zone, and launching enforces CAN-SPAM (an address on every sending domain, a working unsubscribe link), the bounce circuit breaker and merge fields that will fill before it will go live. It marks itself Completed once it has nothing left to send.
Create and update
API details (Tier 0 / self-hosters) · POST /v1/campaigns▸
curl -X POST https://app.yourcompany.com/v1/campaigns \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Q3 outbound — agencies",
"template": "Hi there — {quick question|one question} for you today?",
"aiPromptTemplate": "Write a 2-sentence opener to {{firstName}} at {{company}}, referencing {{recentNews}}.",
"aiProvider": "GEMINI",
"unsubscribeUrlTemplate": "https://yourcompany.com/unsubscribe?email={{email}}"
}'API details (Tier 0 / self-hosters) · Response (201) — includes contentQuality▸
{
"id": "camp_g7h8i9",
"name": "Q3 outbound — agencies",
"status": "DRAFT",
"contentQuality": { "spamScore": { "score": 2, "flaggedTerms": [] }, "spintaxGroupCount": 1 }
}PATCH /v1/campaigns/:id takes the same content fields (plus bounceRateThreshold and pausedForBounceRate for a dashboard’s “resume” action) and recomputes contentQuality whenever template or subject changes. It refuses status and any unknown field with 422, so a campaign only goes live through the launch check below. Malformed spintax — an unbalanced {/} — returns 422 on either call, since it would break rendering at send time, not just read oddly.
Native spintax
Syntax: {option one|option two|option three}, resolved to one uniformly-random option per send. Groups can nest. It works independently of AI configuration, so a campaign with no AI provider at all still gets per-send variation instead of one identical template hitting every lead:
API details (Tier 0 / self-hosters) · Spintax in template▸
Hey {there|friend} — {quick|fast} question about your {outbound|cold email} process?Merge fields and fallbacks
{{firstName}}, {{company}} and any column you imported (stored in customFields) fill from the lead in the subject, the first email and every follow-up. Names ignore capitals and underscores, so {{First_Name}} fills the same as {{firstName}}. Add a fallback after a | for leads with nothing in that field: Hi {{firstName|there}}, reads “Hi there,” for a lead with no first name.
A blank value counts as missing, so it takes the fallback too. A field with no fallback would otherwise go out as literal {{text}}, so launch refuses it: FIELD_UNKNOWN when no lead has that column, FIELD_BLANK (with missingCount) when some leads have it empty. Values that contain $ fill as written.
BYOK AI personalization
Save a Gemini or Claude key once. Saving makes one small call to the model you chose, so a key that can’t use that model (a free Gemini key with no quota for it, say) is refused at save with a plain reason, not discovered later when every send falls back. A blank key keeps the saved one when you only switch models.
API details (Tier 0 / self-hosters) · POST /v1/ai-providers▸
curl -X POST https://app.yourcompany.com/v1/ai-providers \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "provider": "GEMINI", "apiKey": "YOUR_GEMINI_KEY", "model": "gemini-2.5-flash" }'Set aiProvider on the campaign and every send fills aiPromptTemplate’s {{fieldName}} placeholders from the lead’s firstName/lastName/company and its flat customFields, then hands the whole lead context to your key to write the finished body — never the other way around (WarmHawk never routes your key through a shared gateway). Delete a key with DELETE /v1/ai-providers/:provider; campaigns referencing it fall back to sending template unpersonalized rather than breaking.
aiMode picks how much the AI changes:
PERSONALIZE(AI Adjusts, the default). Your email goes out as you wrote it, with one sentence about a real fact from the lead’s data added after the greeting.PROMPT(AI Writes). The AI writes a new email from your instructions, using your own email as the source of the offer and the sign-off.aiWritesSubject: truelets it write the subject too.
In both modes the AI must keep your links, prices and greeting, and may not add links you didn’t write or say how the lead was found. An email that misses gets one retry naming what to keep; a second miss sends your own email instead, logged with aiFallbackReason: "content_dropped". A key that runs out of credit falls back with quota_exceeded.
Every AI-generated send that resolves to an EU recipient gets the EU AI Act Article 50 disclosure marker appended automatically — a fallback (unpersonalized) send has nothing to disclose, so the marker only appears on genuinely AI-written content. See Guardrails & compliance.
Senders and follow-ups
mailboxIds is the list of mailboxes a campaign sends its first emails from. The queue rotates across only those, least recently used first, so one client’s campaign never goes out from another client’s mailbox. New mailboxes are never added to a campaign on their own. A warming mailbox can be picked and joins the rotation once its warm-up finishes.
API details (Tier 0 / self-hosters) · PATCH /v1/campaigns/:id — senders and follow-ups▸
curl -X PATCH https://app.yourcompany.com/v1/campaigns/camp_g7h8i9 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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": true }
]
}'steps holds up to three follow-ups, each waiting waitDays (1–30) after the email before it. Both lists replace the whole set on every call. How a sequence runs:
- Same mailbox. A lead is pinned to the mailbox that sent its first email, and every follow-up goes from it. If that mailbox can’t send, the follow-up waits rather than switching sender.
- Same thread. The subject is “Re:” plus the first subject, with In-Reply-To and References set, so the inbox shows one conversation.
- Follow-ups first. Due follow-ups take a mailbox’s daily capacity before new first emails, so a started sequence keeps its timing.
- Stops on its own. A reply to any email in the thread, a bounce, an unsubscribe or a suppression ends the sequence for that lead.
- Unticking a mailbox stops its new first emails only. It still sends the follow-ups for leads it already started.
Each follow-up’s body is what sends when AI is off or fails; with aiRewrite: true your AI key rewrites it using the campaign’s AI settings. The footer and unsubscribe link are the same as the first email’s, from the pinned mailbox’s domain. waitDays counts calendar days, weekends included.
Send schedule
By default a campaign sends at any hour. A schedule limits it to set days and hours in one time zone. In the dashboard it’s “When it sends” under Send from, which starts at Monday to Friday, 9 to 5, in your browser’s time zone.
API details (Tier 0 / self-hosters) · PATCH /v1/campaigns/:id — Mon–Fri, 9:00–17:00 Chicago time▸
curl -X PATCH https://app.yourcompany.com/v1/campaigns/camp_g7h8i9 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sendTimezone": "America/Chicago",
"sendDays": [1, 2, 3, 4, 5],
"sendStartMinute": 540,
"sendEndMinute": 1020,
"useLeadTimezone": false,
"maxNewLeadsPerDay": 50
}'| Field | What it sets |
|---|---|
| sendTimezone | An IANA zone such as Europe/London. null turns the schedule off and clears the rest. |
| sendDays | At least one day, 0 (Sunday) to 6 (Saturday). |
| sendStartMinute / sendEndMinute | Minutes after local midnight: 540 is 9:00, 1020 is 17:00. The end must come after the start. |
| useLeadTimezone | Use each lead's own time zone, read from a Time zone, Country, State or City column. Leads without one use sendTimezone. |
| maxNewLeadsPerDay | Optional cap on first emails per day for the campaign (1 to 10,000). null means no cap. |
A PATCH can send only the fields that change; they are checked together with the saved ones, and a bad schedule returns 422 with the reason. Each mailbox’s daily limit is spread across the open hours rather than sent in a burst at the start, follow-ups go before new leads, and an email that comes due while the schedule is closed goes at the next opening. Duplicating a campaign copies its schedule.
Launch and pause
API details (Tier 0 / self-hosters) · POST /v1/campaigns/:id/launch▸
curl -X POST https://app.yourcompany.com/v1/campaigns/camp_g7h8i9/launch \
-H "Authorization: Bearer YOUR_API_KEY"Runs the launch check and returns every problem at once in a 422 — no mailbox picked, a sending domain with no mailing address, an unsubscribe link missing on an install with no domain to serve the built-in page, an empty first email or follow-up, a merge field that would go out as literal text (see Merge fields above), or the campaign currently pausedForBounceRate (see Sending safely & domain health) — otherwise sets status: "ACTIVE" and returns any warnings (a mailbox with no sender name, every mailbox still warming, no leads yet). GET /v1/campaigns/:id/launch-check runs the same check without launching. POST /v1/campaigns/:id/pause is the reverse. DELETE /v1/campaigns/:id archives (sets status: "ARCHIVED") rather than hard-deleting — campaign history isn’t personal data, so GDPR erasure is per-lead, not per-campaign.
A sending campaign marks itself COMPLETED once no lead is waiting for a first email or a follow-up. Give it new work (import more leads, add a follow-up) and it goes back to ACTIVE on its own. Paused, draft and archived campaigns are left as they are.
API details (Tier 0 / self-hosters) · GET /v1/campaigns — list view with rollups▸
curl https://app.yourcompany.com/v1/campaigns -H "Authorization: Bearer YOUR_API_KEY"
# each row includes mailboxIds, steps, senders, launch, progress, sendWindow,
# leadsCount, sentCount, repliesCount, domainsCount, lastActivityAt,
# aiWrittenCount, aiFallbackCount
#
# progress: untouched, contacted, replied, bounced, stopped, followUpsDue, sentToday,
# followUpsSent leads that got each follow-up, per step
# upcomingFollowUps [{ position, at, count }] — waiting follow-ups by step and time
# nextSendAt when the campaign next sends
# sendWindow: { open, closesAt, nextOpenAt }, or null with no schedulePreview, test send and duplicate
- Preview.
POST /v1/campaigns/previewrenders the subject and body of any step for a lead, with merge fields filled. Send the draft fields pluscampaignId,stepand eitherleadIdorleadIndex(one of the first three leads). When AI is on it makes one real call on your key;skipAi: trueshows your own text instead, andusesAiin the response says whether AI writes that email at send time. With aleadIdthe preview comes from the mailbox that lead is assigned to, and a follow-up keeps the subject the lead’s thread really has. The response says which mailbox would send it and whether the sender, address or unsubscribe link is missing. Nothing is stored. - Test send.
POST /v1/campaigns/:id/test-sendwith{ "to": "you@yourcompany.com" }sends that email from the first ticked mailbox with a “[Test]” subject. No lead changes and nothing is logged as a send. Its unsubscribe link opens a “This was a test email” page and unsubscribes nobody. - Duplicate.
POST /v1/campaigns/:id/duplicatereturns a new draft named “Copy of …” with the same email, follow-ups, AI settings, unsubscribe link, schedule, senders and bounce threshold. Leads, replies and history stay with the original.
Editing in the dashboard
The campaign builder saves only when you say so, so a half-finished edit never reaches leads:
- Save is always on screen. The header shows Save, or Saved when there’s nothing new. Ctrl+S (Cmd+S on a Mac) saves too.
- Unsaved edits get a bar at the bottom of every step with Discard and Save, and Next reads “Save & next”. Nothing saves when you click away from a field.
- Editing a sending campaign. It keeps sending the saved version until you save. After that, the next email uses the new version, and emails already lined up are checked against new send days and hours first.
To read exactly what a queued lead will get, open the email from the Live Queue side panel.
Questions
Campaigns, AI & content quality: questions worth answering up front
What is the difference between template and aiPromptTemplate?+
template is the literal body sent as-is — or used as a fallback if no AI provider is configured or personalization fails — and it supports spintax {option one|option two} variation. aiPromptTemplate is the instruction handed to your AI key, which then writes the actual send; it supports flat {{fieldName}} placeholders instead of spintax.
Does a low content-quality score block a campaign from launching?+
No. The spam-word score is advisory — computed on every save and returned in the response so the dashboard's Content Quality tab can surface it, but it never hard-blocks a launch. Unbalanced spintax syntax does block a save (422), since it would break rendering at send time.
What happens if my BYOK AI key is missing or the call fails?+
WarmHawk retries once after a short delay, then falls back to sending the campaign's own email rather than stalling the send. The send is logged with aiOutcome AI_FALLBACK and an aiFallbackReason (provider_error, model_unavailable, key_rejected, key_missing, quota_exceeded or content_dropped), and the campaign list counts these as aiFallbackCount, so the lead still gets emailed on schedule and you can see why AI didn't write it.
Why does launching a campaign sometimes return a 422?+
The launch check found something to fix, and the 422 lists every problem at once, not just the first: no mailbox picked to send from (NO_SENDERS), a sending domain with no mailing address (DOMAIN_NO_ADDRESS, one per domain), no working unsubscribe link (NO_UNSUBSCRIBE), the bounce circuit breaker tripped (BOUNCE_PAUSED), an empty first email or follow-up (EMAIL_EMPTY, STEP_EMPTY), a merge field that isn’t a column in your leads (FIELD_UNKNOWN), or a merge field that is empty for some leads and has no fallback (FIELD_BLANK). A campaign with no unsubscribeUrlTemplate of its own uses the unsubscribe page WarmHawk serves on your install’s domain, so NO_UNSUBSCRIBE only refuses an install that has no domain set. GET /v1/campaigns/:id/launch-check runs the same check without launching.
Can a campaign send only during business hours?+
Yes. Give the campaign a send schedule: the days, a start and end time, and an IANA time zone, or tick useLeadTimezone to use each lead’s own time zone. WarmHawk spreads each mailbox’s daily limit across those hours, and anything that falls due outside them waits for the next opening. A campaign with no schedule (sendTimezone null) sends at any hour, which is how campaigns created before the schedule existed keep working.
How do I see an email before it goes to a real lead?+
POST /v1/campaigns/preview renders any step for one of your leads, with merge fields filled and one real AI call when AI is on. POST /v1/campaigns/:id/test-send sends that email to your own address with a “[Test]” subject. Neither touches the lead, and the test email’s unsubscribe link unsubscribes nobody.
Do follow-ups come from a different mailbox if the first one is busy?+
No. A lead is pinned to the mailbox that sent its first email, and every follow-up goes from that one mailbox as a reply in the same thread. If that mailbox can’t send (paused, needs reconnecting, at its daily cap, or its domain lost its address), the follow-up waits rather than switching sender.