Docs
Migrating from v1Warmup

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 verbNew 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}/startPOST /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}/stopPOST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/pause
nonePOST /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. Poll GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup to 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 APINew API
Method + routeGET /v1/warmup-status/{emailAccountId}GET /v2/workspaces/{workspaceId}/accounts/{id}/warmup
Key permission (scope)any keywarmup:read
Rate bucket20/min sharedread
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. Read warmupStatus (PENDING, RUNNING, THROTTLED, MAINTENANCE, PAUSED) with warmupPausedReason, and status (CONNECTED / DISCONNECTED) for the connection.
  • dailySendingLimit → warmupCurrentLimit. sent / received → todaySent / todayReceived. New 7-day totals sevenDaySent / sevenDayReceived.
  • replied, spam and undelivered counters are not on this call. Use "Warmup activity" below, or the account analytics stats call in the Deliverability & reports page.
  • warmupScore and outreachReadinessStatus are gone. Use deliverabilityRate. Readiness is now the outreachReadiness filter on the account list.
  • workspaceId (hashed string) is gone.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
idpathnumberyes-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)TypeWhat it meansOld field
idnumberEmail account id.emailAccountId
emailAddressstringThe mailbox address.-
warmupStatusstringWarmup state: PENDING, RUNNING, THROTTLED, MAINTENANCE, PAUSED.current
warmupPausedReasonstring or nullWhy warmup was paused.-
warmupMaxLimitnumberYour maximum daily warmup sends. The ramp climbs toward it.-
warmupCurrentLimitnumberDaily sending limit in force today.dailySendingLimit
warmupStartDatestring (date-time) or nullWhen warmup first started.-
replyRatenumberTarget reply rate (%) that is configured, not measured.-
todaySent / todayReceivednumberWarmup emails sent and received today.sent / received
sevenDaySent / sevenDayReceivednumberWarmup emails sent and received in the last 7 days.-
deliverabilityRatenumber or nullShare 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

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyKey missing, wrong or revoked.Check the Authorization: Bearer header.
403insufficient_scopeKey has no warmup:read scope.Add the scope to the key.
403workspace_forbiddenKey cannot access this workspace.Use a key for this workspace.
403subscription_pausedThe subscription is paused. Every call is blocked, reads too.Resume the subscription.
404not_foundNo account with this id in this workspace.Check workspaceId and id.
429rate_limit_exceededRead 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 APINew API
Method + routeGET /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 keywarmup:read
Rate bucket20/min sharedread
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 page and limit. The paging values (total, page, limit) are inside data, not in a pagination block.
  • 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

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
idpathnumberyes-The email account id.emailAccountId
pagequerynumbernodefault 1, min 1, max 100000Page number.-
limitquerynumbernodefault 25, min 1, max 100Rows 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)TypeWhat it meansOld field
itemsobject[]The warmup emails on this page.-
items[].idnumberWarmup email id.-
items[].senderEspstringESP (email provider) of the sending mailbox: google, microsoft, other, or a brand like zoho.-
items[].subjectstring or nullEmail subject.-
items[].inboxCategorystringWhere the recipient found it, for example INBOX, PROMOTIONS, SPAM.-
items[].spammedbooleanLanded in spam.spam (was a daily count)
items[].bouncedbooleanBounced.undelivered (was a daily count)
items[].bounceTypestring or nullBounce type, if it bounced.-
items[].opened / items[].openedAtboolean / string or nullOpened, and when (ISO-8601 UTC).-
items[].replied / items[].repliedAtboolean / string or nullReplied to, and when.replied (was a daily count)
items[].rescuedFromSpam / items[].rescuedAtboolean / string or nullWarmup moved it out of spam, and when.-
items[].sentAt / items[].receivedAtstring or nullSend and receive time (ISO-8601 UTC).-
totalnumberTotal rows for this mailbox (all pages).-
pagenumberThis page number.-
limitnumberRows 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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestpage or limit out of range.Keep limit at 100 or less.
401unauthorized / invalid_api_keyKey missing, wrong or revoked.Check the Authorization: Bearer header.
403insufficient_scopeKey has no warmup:read scope.Add the scope to the key.
403workspace_forbiddenKey cannot access this workspace.Use a key for this workspace.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo account with this id in this workspace.Check workspaceId and id.
429rate_limit_exceededRead bucket is empty.Wait error.retry_after seconds.