Email warmup API, for warming at scale.
Warmup is in the public API, so a product or an agency can warm mailboxes it does not own a dashboard for. Bearer auth, six endpoints, and no per-mailbox charge.
The short version
HotHawk's warmup endpoints let you list warming mailboxes with status, score and counters, enable or disable warmup and set per-mailbox limits by ID or filter, read status counts, read one mailbox's score, and set workspace defaults including auto-enrolment of new mailboxes. Bearer token auth, and warmup covers Google and Microsoft mailboxes connected over OAuth.
The endpoints
Base URL https://api.hothawk.ai/v1.
Every request carries a Bearer token. Verified against the live spec on 18 October 2026.
/warmups/mailboxes
List every warming mailbox with its status, warmup score and counters, over a date range. This is the one you poll for a dashboard.
/warmups/mailboxes
Turn warmup on or off and set per-mailbox send and reply limits. Takes mailbox IDs or a filter, so you can act on one mailbox or a whole segment in a single call.
/warmups/mailboxes/stats
Counts of mailboxes in each warmup status. Cheaper than listing everything when you only need the shape of the pool.
/warmups/accounts/{id}
The warmup score for one mailbox, for a per-account health view.
/warmups/settings
Read the workspace warmup defaults, including the default limits and whether new mailboxes are enrolled automatically.
/warmups/settings
Update those defaults. Setting auto-enrolment means a mailbox starts warming the moment it is connected, with no second call.
The full reference, including request and response schemas, is in the API docs.
The four calls you will actually make
1. Read the state of every warming mailbox
Status, warmup score and counters for the workspace. This is the call behind a status dashboard.
curl https://api.hothawk.ai/v1/warmups/mailboxes \
-H "Authorization: Bearer $HOTHAWK_API_KEY"
2. Turn warmup on and set a limit
Pass mailbox IDs, or a filter to act on a whole segment at once, which is the difference between one call and four hundred.
curl -X PATCH https://api.hothawk.ai/v1/warmups/mailboxes \
-H "Authorization: Bearer $HOTHAWK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mailboxIds": ["mbx_123", "mbx_456"],
"warmupEnabled": true,
"dailySendLimit": 30
}'
3. Check the shape of the pool
Counts per status, when you want a health check rather than a full list.
curl https://api.hothawk.ai/v1/warmups/mailboxes/stats \
-H "Authorization: Bearer $HOTHAWK_API_KEY"
4. Make it automatic
Switch on workspace auto-enrolment and every newly connected mailbox starts warming on its own. Most integrations set this once and then never call a warmup endpoint again except to read status.
curl -X PATCH https://api.hothawk.ai/v1/warmups/settings \
-H "Authorization: Bearer $HOTHAWK_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "autoEnrollNewMailboxes": true }'
If you are building an AI SDR or an agency stack
Two things make this workable at scale rather than just possible. Warmup is not billed per mailbox, so warming four hundred mailboxes for your customers costs the same as warming four. And auto-enrolment means warmup is a workspace setting rather than a step in your onboarding flow, so your product does not have to model it.
The constraint to design around is the mailbox type. Warmup covers Google and Microsoft mailboxes connected over OAuth. IMAP mailboxes can be connected for sending and can run campaigns, but they cannot join warmup, so if your customers bring IMAP mailboxes you will want to say so in your own interface rather than leave them wondering why a score never appears. Why the pool's providers matter explains the reasoning.
For what warmup does in the product rather than in code, see email warmup. For the rest of the API surface, including campaigns, leads, labels and webhooks, see the API overview, or run the whole thing from Claude through the MCP server.
Questions
Is there an email warmup API?
Yes. HotHawk exposes warmup over its public REST API with Bearer token auth. You can list warming mailboxes with their status, score and counters, enable or disable warmup and set per-mailbox limits by ID or by filter, read status counts across the workspace, read one mailbox’s warmup score, and manage the workspace defaults including automatic enrolment of newly connected mailboxes.
Can I embed email warmup in my own product?
You can drive it entirely over the API, which is what most people mean by embedding it. Connect a customer’s mailbox, turn warmup on for it, and poll the mailbox list to show status and score inside your own interface. With workspace auto-enrolment switched on, a newly connected mailbox starts warming without a second call, so your onboarding flow does not have to know about warmup at all. HotHawk does not provide a drop-in UI widget; you build the interface and call the API.
Which mailboxes can the API warm?
Warmup covers Google Workspace and Gmail, and Microsoft 365 and Outlook, mailboxes connected over OAuth. The API will not warm an IMAP or SMTP mailbox: those can be connected for sending, including through POST /v1/mailboxes/connect-imap, and they can run campaigns, but they cannot join warmup. Worth handling explicitly in your onboarding, because it is the question that generates support tickets.
How many mailboxes can I warm through the API?
Unlimited mailboxes on every plan, with a fair-use ceiling of 25,000 connected at any one time, and warmup included from $97 a month. There is no per-mailbox warmup charge, which is what makes it workable for an agency or a product warming a lot of mailboxes on behalf of customers.
Does warmup need to be configured per mailbox?
No. Set the workspace defaults once with PATCH /v1/warmups/settings, including automatic enrolment, and new mailboxes inherit them. Per-mailbox limits are available through PATCH /v1/warmups/mailboxes when you want to override the default for a specific mailbox or a filtered set, but the common case needs no per-mailbox call at all.
What does the warmup score mean?
It is a per-mailbox health figure you can read for one mailbox or across the workspace, intended for showing progress and spotting a mailbox that needs attention. Treat it as a health indicator rather than a prediction of campaign results: it describes the mailbox’s warmup history, not where your next campaign will arrive.