Docs
Migrating from v1Warmup

Pause warmup to Bulk pause warmup

Stops warmup sending on a mailbox but keeps its settings and progress. Call "Resume warmup" to continue.

Pause warmup

Stops warmup sending on a mailbox but keeps its settings and progress. Call "Resume warmup" to continue.

Old APINew API
Method + routePOST /v1/warmup-settings/{emailAccountId}/stopPOST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/pause
Key permission (scope)any keywarmup:manage
Rate bucket20/min sharedwrite
Plan needed--

What changed

  • Renamed from stop to pause. There is no body.
  • The response is the full email account object in data (the old call returned an empty 200).
  • Old 422 warmup_not_active → new 400 invalid_request ("already paused or not started").
  • To start again, call resume, not enable.

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 POST "$TI_BASE_URL/v2/workspaces/42/accounts/123/warmup/pause" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/warmup-settings/123/stop" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new)

200 OK. data is the full email account, the same as "Get warmup status". warmupStatus can show the old value for a few seconds, until the warmup worker processes the change.

{
  "data": {
    "id": 123,
    "emailAddress": "jane@acme.com",
    "warmupStatus": "PAUSED",
    "warmupPausedReason": null,
    "warmupCurrentLimit": 18
  },
  "meta": {
    "request_id": "req_9a1e6b02",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

(Shortened: the real response has every account field.)

Response (old)

Empty 200 (no body documented).

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestWarmup is already paused or has not started.Nothing to do; read the state with "Get warmup status".
401unauthorized / invalid_api_keyKey missing, wrong or revoked.Check the Authorization: Bearer header.
403insufficient_scopeKey has no warmup:manage scope.Add the scope to the key.
403workspace_forbiddenKey cannot access this workspace.Use a key for this workspace.
403forbiddenThe key's user is below editor role.Use a key with editor rights.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo account with this id in this workspace.Check workspaceId and id.
409conflictA bulk action is running on this mailbox.Wait and retry.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.

Resume warmup

Restarts warmup on a mailbox you paused, or one the system suspended for a reason you can clear. It continues from where the ramp stopped.

Old APINew API
Method + routenone - new (the old start covered this)POST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/resume
Key permission (scope)none - newwarmup:manage
Rate bucketnone - newwrite
Plan needednone - new- (the number of warming mailboxes is capped by plan)

What changed

  • New call. In the old API you called start again after stop. Now use resume after pause.
  • Some suspensions (for example high bounce or spam rates) cannot be resumed by hand. They clear by themselves when the problem recovers; resume returns 400 invalid_request.
  • Resume does not re-check DNS. If a required DNS record is failing, run the DNS re-check first, then resume.
  • The response is the full email account object in data.

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-
idpathnumberyes-The email account id.-

Request body

No body.

Example request (new)

curl -X POST "$TI_BASE_URL/v2/workspaces/42/accounts/123/warmup/resume" \
  -H "Authorization: Bearer ti_ws_your_key"

Response (new)

200 OK. data is the full email account, the same as "Get warmup status". warmupStatus can show the old value for a few seconds, until the warmup worker processes the change.

{
  "data": {
    "id": 123,
    "emailAddress": "jane@acme.com",
    "warmupStatus": "RUNNING",
    "warmupPausedReason": null,
    "warmupCurrentLimit": 18
  },
  "meta": {
    "request_id": "req_5f7a0c44",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

(Shortened: the real response has every account field.)

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestThe mailbox is not paused or suspended; the suspension clears only by itself; or the address hard-bounced repeatedly and was removed from warmup.Read error.message. Wait, or fix the mailbox.
401unauthorized / invalid_api_keyKey missing, wrong or revoked.Check the Authorization: Bearer header.
403insufficient_scopeKey has no warmup:manage scope.Add the scope to the key.
403workspace_forbiddenKey cannot access this workspace.Use a key for this workspace.
403warmup_limit_reachedYour plan already warms the maximum number of mailboxes.Pause another mailbox, or upgrade.
403forbiddenA required DNS record is failing; or the key's user is below editor role.Fix DNS, run the DNS re-check, then resume.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo account with this id in this workspace.Check workspaceId and id.
409conflictA bulk action is running on this mailbox.Wait and retry.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.

Bulk start warmup

Starts warmup on many mailboxes in one call. Mailboxes that cannot start are listed in failed; the others still start.

Old APINew API
Method + routePOST /v1/warmup-settings/bulk-action with "action": "start"POST /v2/workspaces/{workspaceId}/accounts/bulk/warmup/enable
Key permission (scope)any keywarmup:manage
Rate bucket20/min sharedbulk
Plan needed-- (the number of warming mailboxes is capped by plan)

What changed

  • The old call is split in two: this one (start) and "Bulk pause warmup". There is no action field.
  • emailAccountIds → ids. The limit is now 200 ids (was 50).
  • tags is gone. To act on a tag, first list ids with GET /v2/workspaces/{workspaceId}/accounts?tags=sales, then send those ids.
  • Response results[] (emailAccountId, status, error_code, message) → succeeded (list of ids) and failed (list of { id, error }).
  • Each id goes through the same checks as "Start warmup" (DNS, send/receive check, plan cap). Ids are processed one by one, so the plan cap is respected.
  • Bulk enable does not resume paused mailboxes; they appear in failed. Resume them one by one with "Resume warmup".

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
idsinteger[]yes1–200 ids, no duplicatesEmail account ids to start.emailAccountIds (max 50)

Removed: action, tags. Sending them fails with 400 invalid_request.

Example request (new)

curl -X POST "$TI_BASE_URL/v2/workspaces/42/accounts/bulk/warmup/enable" \
  -H "Authorization: Bearer ti_ws_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [123, 124, 125] }'

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/warmup-settings/bulk-action" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emailAccountIds": [123, 124, 125], "action": "start" }'

Response (new)

200 OK, even when some ids fail.

New field (inside data)TypeWhat it meansOld field
succeedednumber[]Ids where warmup was started.results[] with status: "ok"
failedobject[]Ids that were not started.results[] with status: "error"
failed[].idnumberThe id.results[].emailAccountId
failed[].errorstringShort machine-readable reason.results[].error_code

failed[].error is not one of the public error.code values, so do not branch on its exact text. Treat any entry in failed as "not started". To learn why, call "Start warmup" on that id alone; it returns the public error.code (for example mailbox_verification_pending or warmup_limit_reached).

{
  "data": {
    "succeeded": [123, 124],
    "failed": [
      { "id": 125, "error": "<reason code>" }
    ]
  },
  "meta": {
    "request_id": "req_0c4f7e18",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "results": [
    { "emailAccountId": 123, "status": "ok" },
    { "emailAccountId": 125, "status": "error", "error_code": "warmup_already_active", "message": "Warmup is already active." }
  ]
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestids missing, empty, over 200, has duplicates, or old fields (action, tags, emailAccountIds) sent.Fix the body.
401unauthorized / invalid_api_keyKey missing, wrong or revoked.Check the Authorization: Bearer header.
403insufficient_scopeKey has no warmup:manage 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.
429rate_limit_exceededBulk bucket is empty.Wait error.retry_after seconds.

Bulk pause warmup

Pauses warmup on many mailboxes in one call. Mailboxes that cannot be paused are listed in failed; the others are still paused.

Old APINew API
Method + routePOST /v1/warmup-settings/bulk-action with "action": "stop"POST /v2/workspaces/{workspaceId}/accounts/bulk/warmup/pause
Key permission (scope)any keywarmup:manage
Rate bucket20/min sharedbulk
Plan needed--

What changed

  • The old call is split in two: this one (pause) and "Bulk start warmup". There is no action field.
  • emailAccountIds → ids. The limit is now 200 ids (was 50).
  • tags is gone. List ids first with GET /v2/workspaces/{workspaceId}/accounts?tags=sales.
  • Response is succeeded (ids) and failed ({ id, error }), not results[].

Path and query parameters

NameInTypeRequiredDefault / limitsWhat it meansOld name
workspaceIdpathnumberyes-Your TrulyInbox workspace id.-

Request body

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
idsinteger[]yes1–200 ids, no duplicatesEmail account ids to pause.emailAccountIds (max 50)

Removed: action, tags. Sending them fails with 400 invalid_request.

Example request (new)

curl -X POST "$TI_BASE_URL/v2/workspaces/42/accounts/bulk/warmup/pause" \
  -H "Authorization: Bearer ti_ws_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [123, 124, 125] }'

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/warmup-settings/bulk-action" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emailAccountIds": [123, 124, 125], "action": "stop" }'

Response (new)

200 OK, even when some ids fail.

New field (inside data)TypeWhat it meansOld field
succeedednumber[]Ids where warmup was paused.results[] with status: "ok"
failedobject[]Ids that were not paused (for example already paused, or not found).results[] with status: "error"
failed[].idnumberThe id.results[].emailAccountId
failed[].errorstringShort machine-readable reason.results[].error_code

failed[].error is not one of the public error.code values, so do not branch on its exact text. Call "Pause warmup" on that id alone to get the public error.code.

{
  "data": {
    "succeeded": [123, 124],
    "failed": [
      { "id": 125, "error": "<reason code>" }
    ]
  },
  "meta": {
    "request_id": "req_7b2e9d31",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "results": [
    { "emailAccountId": 123, "status": "ok" },
    { "emailAccountId": 125, "status": "error", "error_code": "warmup_not_active", "message": "Warmup is not active." }
  ]
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
400invalid_requestids missing, empty, over 200, has duplicates, or old fields sent.Fix the body.
401unauthorized / invalid_api_keyKey missing, wrong or revoked.Check the Authorization: Bearer header.
403insufficient_scopeKey has no warmup:manage 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.
429rate_limit_exceededBulk bucket is empty.Wait error.retry_after seconds.