WarmHawk
Docs / Guides / Sending safely & domain health

Guardrails that protect a domain before it’s trashed, not after.

Three layers work together: a throttled, jittered send queue; a bounce circuit breaker that auto-pauses a bad list; and domain health checks — SPF/DKIM/DMARC, blocklist status, and seed-inbox placement sampling — you can pull on demand.

WarmHawk protects domain reputation structurally: the send queue enforces an 8-minute cadence floor plus jitter per mailbox, a bounce/complaint circuit breaker auto-pauses a campaign past 5% bounces on at least 20 sends and a mailbox past 3% over its last 7 days on at least 50, a mailbox that gets a “try again later” slows to half pace, and GET /v1/domains/:id/placement-sample reports real seed-inbox placement results — never a self-reported score.

Queue: status and pause

API details (Tier 0 / self-hosters) · GET /v1/queue/status▸
curl https://app.yourcompany.com/v1/queue/status -H "Authorization: Bearer YOUR_API_KEY"
API details (Tier 0 / self-hosters) · Response▸
{
  "counts": { "waiting": 3, "active": 1, "delayed": 12, "completed": 240, "failed": 2 },
  "isPaused": false,
  "jobs": [
    {
      "id": "1042",
      "state": "delayed",
      "mailboxEmail": "you@yourcompany.com",
      "leadEmail": "jane@prospect-co.com",
      "campaignName": "Q3 outbound — agencies",
      "scheduledFor": "2026-08-23T18:04:00.000Z",
      "attemptsMade": 0
    }
  ],
  "sentByDay": [ /* sends per day, last 6 days and today */ ],
  "failedToday": 0,
  "queuedByDay": [ /* every queued email, counted by the day it's due */ ],
  "expectedByDay": [ /* what active campaigns are expected to send for the rest of today, then each of the next 7 days */ ],
  "offDays": [ /* days no active campaign sends on, such as a weekend */ ],
  "mailboxes": [ /* each mailbox's sent, warm-up, queued and cap, 2 days either side of today */ ],
  "throttling": {
    "cadenceFloorSeconds": 480,
    "jitterSeconds": 240,
    "minGapSeconds": 630,
    "maxGapSeconds": 1050
  }
}

cadenceFloorSeconds: 480 is the real, structural 8-minute minimum between two sends from the same mailbox. On top of it goes a random 4 to 8 minutes and plus or minus 90 seconds of noise, so sends don’t land on a suspiciously exact clock tick. The random part only ever adds, so minGapSeconds and maxGapSeconds give the real gap: 10.5 to 17.5 minutes. jobs lists the first 50 waiting/active/delayed jobs; GET /v1/queue/jobs lists every queued email, filtered by mailbox or day. The queue is BullMQ-backed and real — pausing it is a genuine Redis-level pause, not a cosmetic flag:

API details (Tier 0 / self-hosters) · POST /v1/queue/pause▸
curl -X POST https://app.yourcompany.com/v1/queue/pause \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "paused": true }'

Watch it in the dashboard: Live Queue

The Live Queue page shows the same queue, refreshed every 5 seconds:

  • Queued, Sending now, Sent today, Failed today. Emails waiting to go, going now, and the campaign emails that went out or failed since midnight UTC. Warm-up emails aren’t counted.
  • Sends by day. What went out each day this past week, then for today and each day ahead what’s queued and what your active campaigns are expected to send. Today’s bar stacks what’s still to come on top of what already went out, so it isn’t empty before your send hours open. Each mailbox only books its next email, so the expected count is an estimate from its cap, each campaign’s send days and hours, follow-ups due and leads left. Replies, bounces and unsubscribes end sequences early, so it’s usually a little high. A day none of your active campaigns sends on, such as a weekend, reads Off.
  • Per-mailbox daily caps. For each mailbox, what it sent against each day’s cap for the last two days and today (with what’s still queued and expected today), then what’s queued and expected for the next two. Warm-up emails don’t count toward the cap, so their count is only in each cell’s hover text, and a warming mailbox shows which warm-up day it’s on. Each campaign a mailbox sends for gets its own line. Mailboxes with a running campaign come first, then warming mailboxes, the furthest along first.
  • Throttling. The real gap between emails from one mailbox, 10.5 to 17.5 minutes.

Click a mailbox row, today’s bar on the chart (once emails are booked), or View queue and a side panel lists the queued emails, grouped by day, soonest first. Other days on the chart show what’s expected when you hover them. When the list is empty, the panel says why: the queue is paused, no campaign is running, send hours haven’t started (with the time they open), today isn’t a send day, send hours are over, the next emails are being booked, or the mailbox hit its daily limit. Open an email and you see that lead’s emails, one tab per step: the ones already sent, the next one with when it goes, and later follow-ups with their wait. Each tab shows the campaign text filled in for that lead. When AI writes an email, the tab shows the text AI starts from; Preview with AI shows a sample of what AI would write.

Pause queue on the same page holds every campaign until you resume it; nothing is dropped. To stop just one campaign, use Pause on that campaign instead.

Send hours and the daily limit

Each mailbox has a daily limit (dailyCap), counted over the last 24 hours rather than reset at midnight, so a burst late one evening still counts the next morning. How the queue uses it:

  • Spread, not burst. With a send schedule the limit is spread across the open hours, never closer together than the 8-minute floor plus jitter. A mailbox sending 40 a day over an 8-hour window sends about one every 12 minutes.
  • Follow-ups first. Due follow-ups take the day’s capacity before new first emails, so a started sequence keeps its timing.
  • Closed hours wait. An email that comes due while the schedule is closed goes at the next opening, not the moment it was due.
  • A ramp after warm-up. A mailbox that has just finished warm-up starts at 5 campaign emails a day and grows 20% a day until it reaches its daily limit.

A campaign with no schedule sends at any hour, still one email per mailbox every 10.5 to 17.5 minutes.

The bounce circuit breaker

Evaluated from real ExecutionLog data after every bounce, not a separate monitoring system. There are two breakers, one per campaign and one per mailbox.

Mailbox: 3% over the last 7 days. Once a mailbox has sent at least 50 emails in the last 7 days and more than 3% of them bounced, it pauses (status: PAUSED, with autoFlaggedAt set) for every campaign it sends for. Mailbox providers judge a sender on its recent mail, so the window rolls: an old clean record can’t hide a bad week. A provider’s sending limit (Gmail’s 550 5.4.5) isn’t a bounce and doesn’t count. Live Queue shows each mailbox’s 7-day rate, amber from 2% and red past 3%.

Campaign: 5% overall. Once a campaign has at least 20 sends and its bounce rate exceeds 5% (configurable via the campaign’s bounceRateThreshold), it flips pausedForBounceRate: true. From that point, POST /v1/campaigns/:id/launch refuses with 422 until a human clears the flag via PATCH /v1/campaigns/:id { "pausedForBounceRate": false } — deliberately not an automatic reset, since the underlying list-quality problem needs addressing first, not just waiting out. In the dashboard the campaign shows Stopped: bounces, and its Resume button clears the flag after a confirm. A bounced lead has no Suppress action: it’s never emailed again anyway, and suppressing it would take it out of the bounce rate.

Slowing down after a “try again later”. When a send fails with a temporary refusal (a 4xx reply, a rate limit or a daily sending limit), that mailbox runs at half pace for the next 24 hours: half its daily limit, and twice the gap between its emails. Nothing is dropped; its leads just go more slowly. That’s what Google’s sender guidelines ask: when messages start being deferred, reduce the sending volume.

Checking an address before the first email

Optional, and off until you turn it on. Before a lead’s first email, the worker asks the lead’s mail server whether the mailbox exists: it connects on port 25, names the lead’s address and a made-up one on the same domain, then hangs up. Nothing is sent.

  • A clear “no such mailbox”, or a domain with no mail server at all, stops the lead as FAILED with the reason in its log (“Not sent: … Checked before sending, so nothing went out.”). It never bounces off your mailbox and doesn’t count toward the bounce rate or the mailbox’s daily sends. The mailbox gets its slot back, so its next lead is timed from its last real send, not held back by the dead one.
  • A placeholder address such as name@example.com, you@yourdomain.com or an image file name scraped off a web page (logo@2x.png) stops the same way, without asking any server.
  • “Try again later” (greylisting) puts the lead back for 30 to 60 minutes and asks again, up to three times, since greylisting servers take the second try. After the third it sends. It’s a delay, never a block.
  • Anything else that isn’t clear sends as before: a timeout, a block aimed at your server, or a server that accepts every address (which the made-up address shows).
  • Risky leads are spread out, not held. A server that accepts every address, and Yahoo and AOL addresses (they accept every address when asked and bounce later), are still sent. Where a campaign has a confirmed address ready too, a mailbox doesn’t get two risky leads in a row.
  • Follow-ups skip it. A lead that got its first email already passed.

Your server needs outbound port 25 (many hosts block it until you ask) and a server name whose A record and reverse DNS match: mail servers refuse to talk to one whose name and reverse DNS disagree. Give the name an SPF record such as v=spf1 a -all. Once the server name checks out, the address check turns on with it, as check@ that name. To use a different name for the check, set it in core’s .env/.env and run warmhawk update; it wins over the server name:

API details (Tier 0 / self-hosters) · .env/.env (optional)▸
ADDRESS_CHECK_HELO=mail-check.yourcompany.com
# optional, defaults to check@<the name above>
ADDRESS_CHECK_MAIL_FROM=

The worker checks the next few leads due a little before their turn, every minute, and keeps each answer for a day, so the send itself rarely waits on a check.

Domain checks: SPF/DKIM/DMARC + blocklists

API details (Tier 0 / self-hosters) · POST /v1/domains/:domain/check — keyed by domain NAME▸
curl -X POST https://app.yourcompany.com/v1/domains/yourcompany.com/check \
  -H "Authorization: Bearer YOUR_API_KEY"

Runs live DNS-TXT resolution for SPF/DKIM/DMARC plus a Spamhaus DBL domain-blocklist lookup in one round trip and persists the result on the Domain row. The same full check also runs on its own every hour for every domain, so a DKIM key that disappears turns the badge red without anyone pressing Re-check. Blocklist lookups go straight to Spamhaus’s own nameservers, since Spamhaus refuses public resolvers like 1.1.1.1 and 8.8.8.8.

DKIM selectors. DNS has no way to list a domain’s DKIM keys, so WarmHawk tries the default selector of every common provider (Google Workspace, Microsoft 365, Cloudflare, SendGrid, Mailgun, Zoho, Fastmail, Proton, Brevo, Resend, HubSpot and more). If none is found the badge reads Pending, not Fail. Providers that mint a selector per customer — Amazon SES, Postmark, ZeptoMail — need it saved on the domain: set dkimSelector (the part before ._domainkey) in the dashboard or via PATCH /v1/domains/:id. Once saved, a missing or revoked key there is a Fail. A one-off ?selector= on the check route overrides it for that call.

Personal mailboxes. A domain like gmail.com, yahoo.com or outlook.com is flagged personalProvider: true. Its DNS belongs to the provider, so the checks say so instead of asking you to fix records you can’t change, and the dashboard doesn’t alert on it.

Mailing address per domain

CAN-SPAM needs a postal address in every campaign email’s footer. WarmHawk keeps it on the sending domain, so an agency’s client brands each print their own and never share one; there is no install-wide fallback. Adding a domain never needs an address. A campaign can’t launch while any domain it sends from has none, and a mailbox whose domain loses its address stops sending until one is added back. Warm-up emails carry no footer and need no address.

API details (Tier 0 / self-hosters) · PATCH /v1/domains/:id — set the address▸
curl -X PATCH https://app.yourcompany.com/v1/domains/dom_a1b2c3 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme Logistics",
    "mailingAddressParts": {
      "businessName": "Acme Logistics LLC",
      "street": "100 Main St", "suite": "Suite 200",
      "city": "Denver", "region": "CO", "postalCode": "80202", "country": "USA"
    }
  }'

mailingAddressParts needs at least street, city and country, and WarmHawk builds the printed mailingAddress from it. You can send mailingAddress as one block of text instead (up to 500 characters). Clearing an address that campaigns send with returns 409 ADDRESS_IN_USE with the campaigns listed; send confirm: true to clear it anyway. PUT /v1/instance-settings, the old install-wide address, now answers 410 Gone.

Every campaign email names your server three times: in the footer’s unsubscribe link, in the List-Unsubscribe header behind Gmail’s Unsubscribe button, and in the name your server gives when it connects to send, which the recipient sees in the Received: header. By default that’s the install’s own domain (WARMHAWK_DOMAIN). If you send for several brands from one server, that ties them all to one name, and to each other. A link domain such as link.yourbrand.com gives each sending domain its own.

  1. DNS. In the brand’s zone, point link at your server: an A record to its IP, or a CNAME to your WARMHAWK_DOMAIN.
  2. Your server. Run warmhawk link-domain add link.yourbrand.com. It adds an nginx block for the host and gets it a Let’s Encrypt certificate. Behind your own TLS proxy, add --no-tls and have the proxy forward the host to WarmHawk’s nginx.
  3. The dashboard. Domain Health → the sending domain → Link domain, enter the host, then Check now.
API details (Tier 0 / self-hosters) · CLI▸
warmhawk link-domain add link.yourbrand.com   # nginx block + certificate
warmhawk link-domain list
warmhawk link-domain remove link.yourbrand.com

Used only once it answers. An unsubscribe link that doesn’t open breaks CAN-SPAM, so a new link domain starts unchecked and emails keep the default link until a check passes. The check opens https://link.yourbrand.com/unsubscribe/ping and expects an answer only your install can give, so a page on another server never passes. It re-runs every hour with the domain’s other checks. If the host stops answering (DNS moved, a certificate lapsed), emails go back to the default link within the hour.

The link host serves the unsubscribe page and nothing else. Every other path, the API and the dashboard included, is a 404 there. Links in emails already sent keep working, since the default host still answers them.

API details (Tier 0 / self-hosters) · PATCH /v1/domains/:id, then check by NAME▸
curl -X PATCH https://app.yourcompany.com/v1/domains/dom_a1b2c3 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "linkDomain": "link.yourbrand.com" }'

curl -X POST https://app.yourcompany.com/v1/domains/yourbrand.com/link-domain/check \
  -H "Authorization: Bearer YOUR_API_KEY"

The domain then carries linkDomainStatus (PENDING, PASS or FAIL), linkDomainError with the reason in plain words, and linkDomainCheckedAt. Changing the host puts it back to PENDING; sending null or "" removes it.

Server name

Gmail, Outlook.com, Yahoo and most other mail servers write your server’s reverse DNS (PTR) into every email’s Received: header. A new server’s reverse DNS is its host’s default, something like static.7.113.0.203.clients.your-server.de, so every email names your hosting company. A server name is the one host name your install introduces itself with instead. Set it once per server:

  1. DNS. An A record for mail.yourcompany.com to the server’s IP, and an AAAA record if it has IPv6. Not proxied.
  2. Reverse DNS. In your server host’s control panel (usually Networking or Reverse DNS), set each IP’s reverse DNS to the same name, IPv6 included.
  3. Your server. Run the command below. It saves the name in core’s .env/.env, restarts the API and worker, and checks both directions.
API details (Tier 0 / self-hosters) · CLI▸
warmhawk server-name set mail.yourcompany.com
warmhawk server-name check     # after changing DNS or reverse DNS
warmhawk server-name clear

Used only once it checks out. Every address the name points at must have reverse DNS naming it back. Until it does, nothing changes. Domain Health shows the name, its status and, when it fails, what to change (“The reverse DNS of 203.0.113.7 is …, not mail.yourcompany.com”), with a Check now button. It re-checks at startup and every hour while in use.

Once it passes, it is the connection name for every sending domain without a checked link domain (a link domain still wins for its own brand), and the address check turns on with it unless ADDRESS_CHECK_HELO names another. Unsubscribe links don’t change.

API details (Tier 0 / self-hosters) · GET /v1/instance-settings · POST /v1/instance-settings/server-name/check▸
{
  "publicHost": "app.yourcompany.com",
  "serverName": {
    "name": "mail.yourcompany.com",
    "status": "PASS",            // PENDING | PASS | FAIL
    "error": null,               // the reason in plain words on FAIL
    "checkedAt": "2026-10-15T20:00:00.000Z"
  },
  "addressCheckName": "mail.yourcompany.com"   // null while the check is off
}

The check route returns the new serverName, or 404 while no name is set.

Seed-inbox placement sampling

A small, fixed set of email accounts you own are BCC’d on real campaign sends; WarmHawk reports which folder each one landed in — inbox, spam, or promotions. Manage the seed inboxes via GET/POST/PATCH/DELETE /v1/seed-accounts, then pull the rollup per domain:

API details (Tier 0 / self-hosters) · GET /v1/domains/:id/placement-sample — id-keyed▸
curl https://app.yourcompany.com/v1/domains/dom_a1b2c3/placement-sample \
  -H "Authorization: Bearer YOUR_API_KEY"
API details (Tier 0 / self-hosters) · Response▸
{
  "domainId": "dom_a1b2c3",
  "domainName": "yourcompany.com",
  "label": "Placement sampling across 4 seed inboxes — not full inbox-placement testing.",
  "sampledSeedAccountCount": 4,
  "totalChecks": 18,
  "byFolder": { "INBOX": 12, "SPAM": 3, "PROMOTIONS": 3, "UNCLASSIFIED": 0 },
  "inboxPlacementRate": 0.667,
  "mostRecentCheckAt": "2026-08-22T09:14:00.000Z",
  "results": []
}

The response is deliberately, explicitly labeled “placement sampling,” never “inbox-placement testing” — a small owned sample is directional evidence from real sends, not a statistically exhaustive placement panel, and WarmHawk doesn’t market it as one.

Every structural guardrail on this page — the cadence floor, the circuit breaker, CAN-SPAM enforcement — is covered end to end, alongside CSV-injection defense and GDPR erasure, in Guardrails & compliance.

Questions

Sending safely & domain health: questions worth answering up front

What is the 8-minute cadence floor?+

The minimum spacing the send queue enforces between two sends from the same mailbox, before jitter is layered on top — a structural floor, not a suggestion, so a burst of newly-imported leads can never blast a mailbox at machine speed. The jitter only ever adds, so the real gap is 10.5 to 17.5 minutes, about 14 on average.

What triggers the bounce circuit breaker, and what does it do?+

Two breakers. A campaign stops once more than 5% of its sends bounce, after at least 20 sends: it is flagged pausedForBounceRate and further launches are refused with a 422 until it is explicitly resumed. A mailbox pauses once more than 3% of its sends in the last 7 days bounce, after at least 50 sends in those 7 days, so an old clean record can't hide a bad week.

Is placement sampling the same thing as a warmup "heat score"?+

No, and WarmHawk is deliberate about the distinction. Placement sampling BCCs real campaign sends to a small, fixed set of seed inboxes you own and reports which folder each landed in — a real, first-party signal from an actual send, explicitly labeled as sampling across N seed inboxes, never marketed as exhaustive inbox-placement testing.

Is a domain health check keyed by domain id or domain name?+

POST /v1/domains/:domain/check is keyed by the domain NAME (e.g. yourcompany.com), unlike this API's other domain routes which use the internal id — it's the shape a customer actually thinks in when re-checking a domain.

Can each brand I send for have its own unsubscribe link?+

Yes. Give each sending domain a link domain such as link.yourbrand.com: point it at your server, run warmhawk link-domain add, and press Check now under Domain Health. Once the check passes, that brand's footer link, List-Unsubscribe header and connection name use it instead of your install's own domain. Until it passes, emails keep the default link.

Why does my hosting company's name show up in the headers of emails I send?+

Gmail, Outlook.com, Yahoo and most other mail servers record your server's reverse DNS in every email's Received: header, and a new server's reverse DNS is its host's default name. Set a server name such as mail.yourcompany.com: an A record to your server, the same name as the IP's reverse DNS in your host's control panel, then warmhawk server-name set mail.yourcompany.com. Once both directions match, WarmHawk uses it as its connection name and for the address check.