Queue, domains & webhooks.
The send queue, domain health checks, and — explicitly — what outbound webhooks exist today (none) versus what’s planned.
GET /v1/queue/status reports real BullMQ counts, pause state, sends by day, each mailbox’s sent, queued and cap counts, and the real gap between sends (10.5 to 17.5 minutes from one mailbox); GET /v1/queue/jobs lists every queued email, soonest first; POST /v1/queue/pause is a genuine Redis-level pause. Domain routes cover SPF/DKIM/DMARC + blocklist checks (keyed by domain name) and seed-inbox placement sampling (keyed by id). Outbound webhooks — WarmHawk calling your URL on an event — are Planned; no such system exists in core-engine yet.
Queue
| Route | What it does |
|---|---|
| GET /v1/queue/status | Returns { counts, isPaused, jobs, sentByDay, failedToday, queuedByDay, expectedByDay, offDays, mailboxes, throttling }. counts.waiting, active and delayed count email jobs only, not the nightly system job. counts.completed and counts.failed are BullMQ’s own records (finished jobs kept 24 hours, skipped slots included; crashed jobs kept 7 days), not emails sent or failed: for those, read sentByDay’s today and failedToday, the campaign emails that failed since midnight UTC. jobs is the first 50 pending jobs. sentByDay is sends per UTC day for the last 6 days and today. queuedByDay counts every pending job, not just those 50, by the UTC day it is due (overdue ones count toward today), soonest day first. The queue only holds each mailbox’s next email, so expectedByDay estimates what active campaigns will send for the rest of today and on each of the next 7 UTC days, from each mailbox’s cap (less what it already sent or has booked today), each campaign’s send days and hours, max new leads per day, follow-ups due and leads left (recomputed at most once a minute). offDays lists the UTC days, from 6 days back to 7 ahead, on which no active campaign sends, such as a Monday-to-Friday campaign’s weekend. mailboxes gives each mailbox its campaigns and, for the 2 days either side of today, sent, warmup, queued, expected (0 before today; today, what’s still to come) and cap. throttling carries cadenceFloorSeconds (480), jitterSeconds, and minGapSeconds / maxGapSeconds, the real gap between two sends from one mailbox. |
| GET /v1/queue/jobs | Every pending send, soonest first, up to 50, with the full match count in total. ?mailboxId= narrows to one mailbox; ?day=YYYY-MM-DD (UTC) to the sends due that day, with overdue ones counting toward today. Each job has its lead, mailbox, campaign, scheduledFor and step (0 = the first email, N = follow-up N). |
| POST /v1/queue/pause | Body: { paused: boolean }. Real BullMQ pause/resume, not cosmetic. |
API details (Tier 0 / self-hosters) · GET /v1/queue/status — response shape▸
{
"counts": { "waiting": 3, "active": 1, "delayed": 12, "completed": 240, "failed": 2 },
"isPaused": false,
"jobs": [ /* the first 50 waiting/active/delayed jobs */ ],
"sentByDay": [ { "day": "2026-10-14", "count": 38 } /* 7 days, oldest first */ ],
"failedToday": 0,
"queuedByDay": [ { "day": "2026-10-15", "count": 3 } /* every pending job, by due day */ ],
"expectedByDay": [ { "day": "2026-10-14", "count": 12 } /* the rest of today, then 7 days */ ],
"offDays": [ "2026-10-17", "2026-10-18" ],
"mailboxes": [
{
"id": "mbx_a1b2c3",
"campaigns": [ { "id": "cmp_x1", "name": "Q4 agencies", "status": "ACTIVE" } ],
"days": [ { "day": "2026-10-14", "sent": 12, "warmup": 4, "queued": 9, "expected": 0, "cap": 25 } /* 5 days */ ]
}
],
"throttling": {
"cadenceFloorSeconds": 480,
"jitterSeconds": 240,
"minGapSeconds": 630,
"maxGapSeconds": 1050
}
}The gap: an 8-minute floor since the mailbox’s last send, plus a random 4 to 8 minutes, plus or minus 90 seconds. The random part only ever adds, so the shortest real gap is 10.5 minutes, not 8. Warm-up emails don’t count toward cap.
API details (Tier 0 / self-hosters) · GET /v1/queue/jobs?day=2026-10-15 — response shape▸
{
"total": 27,
"jobs": [
{
"id": "lead_9f2:mbx_a1b2c3:1791999657597",
"state": "delayed",
"mailboxEmail": "alex@yourcompany.com",
"leadEmail": "sam@prospect.com",
"campaignName": "Q4 agencies",
"scheduledFor": "2026-10-15T14:05:00.000Z",
"attemptsMade": 0,
"leadId": "lead_9f2",
"campaignId": "cmp_x1",
"step": 1
}
]
}To read the email a queued job will send, pass its leadId and step to POST /v1/campaigns/preview with the campaign’s id.
Domains
| Route | What it does |
|---|---|
| GET /v1/domains | List every sending domain on the account, each with mailingAddress, label and usedBy (the campaigns sending from it). |
| POST /v1/domains | Create. Body: { domainName, redirectUrl?, dkimSelector?, label?, mailingAddress?, mailingAddressParts? }. The address is optional here. dkimSelector is the part before ._domainkey; 422 if it is not a valid DNS label. |
| PATCH /v1/domains/:id | Update redirectUrl, dkimSelector, label, linkDomain or the mailing address. Only fields present change; dkimSelector or linkDomain null or "" clears it, and a new linkDomain starts PENDING. Clearing an address that campaigns send with returns 409 ADDRESS_IN_USE unless confirm: true. |
| POST /v1/domains/:domain/check | Keyed by domain NAME, not id. Unified SPF/DKIM/DMARC + blocklist check, plus the link domain if one is set. DKIM uses ?selector= if given, else the saved dkimSelector, else tries common provider selectors (a miss is PENDING). Also runs hourly on its own. |
| POST /v1/domains/:domain/link-domain/check | Keyed by domain NAME. Opens https://<linkDomain>/unsubscribe/ping and saves linkDomainStatus (PASS or FAIL), linkDomainError and linkDomainCheckedAt. Emails use the link domain only while it is PASS. 422 if the domain has no link domain. |
| POST /v1/instance-settings/server-name/check | Checks MAIL_SERVER_NAME both ways (its A/AAAA records point at this server, each IP's reverse DNS names it back) and returns serverName { name, status, error, checkedAt }. Used as the connection name and address-check name only while PASS. GET /v1/instance-settings returns the same serverName plus addressCheckName. 404 while MAIL_SERVER_NAME is blank. |
| GET /v1/domains/:id/placement-sample | Keyed by id. Seed-inbox placement sampling rollup — explicitly labeled as sampling, not exhaustive testing. |
Note the key: domain checks use the domain name (POST /v1/domains/yourcompany.com/check), placement sampling uses the domain id (GET /v1/domains/dom_a1b2c3/placement-sample) — every other domain route in this table is id-keyed. Full walkthrough with response bodies: Sending safely & domain health.
Webhooks — Planned
No outbound webhook system exists in warmhawk-core-engine today — there is no route to register a callback URL and no event dispatcher that calls it. If you need to react to a WarmHawk event today (a new reply, a send completing, a domain going unhealthy), poll the relevant GET route instead: GET /v1/replies, GET /v1/queue/status, or GET /v1/domains/:id/placement-sample. This section exists to say so plainly rather than leave the gap undocumented.
Back to Leads & campaigns or Auth & mailboxes.