Warmup
Move warmup status, settings, start/stop and bulk actions to the /v2 enable, pause and resume routes.
All warmup calls now live under one email account, at /v2/workspaces/{workspaceId}/accounts/{id}/warmup/..., and several verbs have new names.
| Old verb | New verb |
|---|---|
GET /v1/warmup-status/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup |
| "Warmup Activity History" (same call as warmup status) | GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup/activity (real history, paged) |
GET /v1/warmup-settings/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup/settings |
PATCH /v1/warmup-settings/{emailAccountId} | PATCH /v2/workspaces/{workspaceId}/accounts/{id}/warmup/settings |
POST /v1/warmup-settings/{emailAccountId}/start | POST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/enable (first start) or POST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/resume (after a pause or suspension) |
POST /v1/warmup-settings/{emailAccountId}/stop | POST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/pause |
| none | POST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/resume |
POST /v1/warmup-settings/bulk-action with action: "start" | POST /v2/workspaces/{workspaceId}/accounts/bulk/warmup/enable |
POST /v1/warmup-settings/bulk-action with action: "stop" | POST /v2/workspaces/{workspaceId}/accounts/bulk/warmup/pause |
The account id is the same number you used as emailAccountId in the old API.
Three errors you must handle when you start or resume warmup
409 mailbox_verification_pending(enable only). We are still checking that the mailbox can send and receive. Do not retry in a loop. Warmup starts by itself when the check passes. PollGET /v2/workspaces/{workspaceId}/accounts/{id}/warmupto see the state change.400 mailbox_verification_failed(enable only). The mailbox failed the send-and-receive check. Fix the mailbox (login, forwarding, bounces), then call enable again.403 warmup_limit_reached(enable and resume). Your plan already warms the maximum number of mailboxes. Pause another mailbox or upgrade the plan, then try again.
Get warmup status
Returns the current warmup state and ramp progress of one mailbox. Call it to show "is warmup running, and how far along is it".
| Old API | New API | |
|---|---|---|
| Method + route | GET /v1/warmup-status/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup |
| Key permission (scope) | any key | warmup:read |
| Rate bucket | 20/min shared | read |
| Plan needed | - | - |
What changed
- The response is now the full email account object (the same shape as "Get account" in the Email accounts page), wrapped in
data. - The old
current(active,paused,stopped,blocked) is gone. ReadwarmupStatus(PENDING,RUNNING,THROTTLED,MAINTENANCE,PAUSED) withwarmupPausedReason, andstatus(CONNECTED/DISCONNECTED) for the connection. dailySendingLimit→warmupCurrentLimit.sent/received→todaySent/todayReceived. New 7-day totalssevenDaySent/sevenDayReceived.replied,spamandundeliveredcounters are not on this call. Use "Warmup activity" below, or the account analytics stats call in the Deliverability & reports page.warmupScoreandoutreachReadinessStatusare gone. UsedeliverabilityRate. Readiness is now theoutreachReadinessfilter on the account list.workspaceId(hashed string) is gone.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
id | path | number | yes | - | The email account id. | emailAccountId |
Request body
No body.
Example request (new)
curl -X GET "$TI_BASE_URL/v2/workspaces/42/accounts/123/warmup" \
-H "Authorization: Bearer ti_ws_your_key"Example request (old)
curl -X GET "https://lupus-edge.trulyinbox.com/v1/warmup-status/123" \
-H "X-Api-Key: YOUR_API_KEY"Response (new)
200 OK. The table lists the warmup fields. The object also has every other account field (DNS data, tags, provider, and so on).
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
id | number | Email account id. | emailAccountId |
emailAddress | string | The mailbox address. | - |
warmupStatus | string | Warmup state: PENDING, RUNNING, THROTTLED, MAINTENANCE, PAUSED. | current |
warmupPausedReason | string or null | Why warmup was paused. | - |
warmupMaxLimit | number | Your maximum daily warmup sends. The ramp climbs toward it. | - |
warmupCurrentLimit | number | Daily sending limit in force today. | dailySendingLimit |
warmupStartDate | string (date-time) or null | When warmup first started. | - |
replyRate | number | Target reply rate (%) that is configured, not measured. | - |
todaySent / todayReceived | number | Warmup emails sent and received today. | sent / received |
sevenDaySent / sevenDayReceived | number | Warmup emails sent and received in the last 7 days. | - |
deliverabilityRate | number or null | Share of warmup emails that reached the inbox. | warmupScore (closest match) |
{
"data": {
"id": 123,
"emailAddress": "jane@acme.com",
"senderName": "Jane Cooper",
"provider": "GOOGLE_WORKSPACE",
"status": "CONNECTED",
"warmupStatus": "RUNNING",
"warmupPausedReason": null,
"warmupMaxLimit": 40,
"warmupCurrentLimit": 18,
"warmupStartDate": "2026-09-20T09:00:00.000Z",
"replyRate": 30,
"deliverabilityRate": 96.4,
"setupScore": 88,
"todaySent": 12,
"todayReceived": 10,
"sevenDaySent": 84,
"sevenDayReceived": 71,
"tags": [{ "id": 7, "name": "sales" }]
},
"meta": {
"request_id": "req_8c2d41f0",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}(Some account fields are left out of this example to keep it short.)
Response (old)
{
"emailAccountId": 123,
"date": "2026-09-29",
"current": "active",
"strategy": "progressive",
"dailySendingLimit": 18,
"sent": 12,
"received": 10,
"replied": 7,
"spam": 1,
"undelivered": 0,
"warmupScore": 92,
"outreachReadinessStatus": "readyForOutreach",
"workspaceId": null
}Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | Key missing, wrong or revoked. | Check the Authorization: Bearer header. |
| 403 | insufficient_scope | Key has no warmup:read scope. | Add the scope to the key. |
| 403 | workspace_forbidden | Key cannot access this workspace. | Use a key for this workspace. |
| 403 | subscription_paused | The subscription is paused. Every call is blocked, reads too. | Resume the subscription. |
| 404 | not_found | No account with this id in this workspace. | Check workspaceId and id. |
| 429 | rate_limit_exceeded | Read bucket is empty. | Wait error.retry_after seconds. |
Warmup activity
Returns one row per warmup email the mailbox sent, newest first, with what happened to it. Use it for a history view.
| Old API | New API | |
|---|---|---|
| Method + route | GET /v1/warmup-status/{emailAccountId} (the "Warmup Activity History" page pointed to the status call) | GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup/activity |
| Key permission (scope) | any key | warmup:read |
| Rate bucket | 20/min shared | read |
| Plan needed | - | - |
What changed
- The old "history" page was the same call as warmup status. It returned only today's counters. The new call returns real per-email history.
- History is paged with
pageandlimit. The paging values (total,page,limit) are insidedata, not in apaginationblock. - Only the last 90 days are kept. Older emails are deleted and never appear.
- Each row tells you where the email landed (
inboxCategory), whether it bounced or went to spam, and whether it was opened, replied to or rescued from spam.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | - | Your TrulyInbox workspace id. | - |
id | path | number | yes | - | The email account id. | emailAccountId |
page | query | number | no | default 1, min 1, max 100000 | Page number. | - |
limit | query | number | no | default 25, min 1, max 100 | Rows per page. | - |
Request body
No body.
Example request (new)
curl -X GET "$TI_BASE_URL/v2/workspaces/42/accounts/123/warmup/activity?page=1&limit=50" \
-H "Authorization: Bearer ti_ws_your_key"Example request (old)
curl -X GET "https://lupus-edge.trulyinbox.com/v1/warmup-status/123" \
-H "X-Api-Key: YOUR_API_KEY"Response (new)
200 OK.
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
items | object[] | The warmup emails on this page. | - |
items[].id | number | Warmup email id. | - |
items[].senderEsp | string | ESP (email provider) of the sending mailbox: google, microsoft, other, or a brand like zoho. | - |
items[].subject | string or null | Email subject. | - |
items[].inboxCategory | string | Where the recipient found it, for example INBOX, PROMOTIONS, SPAM. | - |
items[].spammed | boolean | Landed in spam. | spam (was a daily count) |
items[].bounced | boolean | Bounced. | undelivered (was a daily count) |
items[].bounceType | string or null | Bounce type, if it bounced. | - |
items[].opened / items[].openedAt | boolean / string or null | Opened, and when (ISO-8601 UTC). | - |
items[].replied / items[].repliedAt | boolean / string or null | Replied to, and when. | replied (was a daily count) |
items[].rescuedFromSpam / items[].rescuedAt | boolean / string or null | Warmup moved it out of spam, and when. | - |
items[].sentAt / items[].receivedAt | string or null | Send and receive time (ISO-8601 UTC). | - |
total | number | Total rows for this mailbox (all pages). | - |
page | number | This page number. | - |
limit | number | Rows per page. | - |
To read everything, request page=1, 2, … while page * limit < total.
{
"data": {
"items": [
{
"id": 998812,
"senderEsp": "google",
"subject": "Quick question about the Q4 rollout",
"inboxCategory": "INBOX",
"spammed": false,
"bounced": false,
"bounceType": null,
"opened": true,
"openedAt": "2026-09-29T09:14:02.000Z",
"replied": true,
"repliedAt": "2026-09-29T09:31:40.000Z",
"rescuedFromSpam": false,
"rescuedAt": null,
"sentAt": "2026-09-29T08:57:11.000Z",
"receivedAt": "2026-09-29T08:57:15.000Z"
}
],
"total": 412,
"page": 1,
"limit": 50
},
"meta": {
"request_id": "req_4b7e90aa",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Response (old)
Same body as "Get warmup status" (old) above: today's counters only, no per-email rows.
Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | page or limit out of range. | Keep limit at 100 or less. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong or revoked. | Check the Authorization: Bearer header. |
| 403 | insufficient_scope | Key has no warmup:read scope. | Add the scope to the key. |
| 403 | workspace_forbidden | Key cannot access this workspace. | Use a key for this workspace. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 404 | not_found | No account with this id in this workspace. | Check workspaceId and id. |
| 429 | rate_limit_exceeded | Read bucket is empty. | Wait error.retry_after seconds. |
Delete an account to Note: Microsoft redirect path
Permanently deletes the account and all its warmup history. This cannot be undone. Use "Disconnect an account" if you want to keep the data.
Get warmup settings
Returns the warmup configuration of one mailbox, plus the plan caps on its limit and reply rate.