Update warmup settings to Start warmup
Changes the warmup configuration of one mailbox. Send only the fields you want to change. The response is the full settings object after the change.
Update warmup settings
Changes the warmup configuration of one mailbox. Send only the fields you want to change. The response is the full settings object after the change.
| Old API | New API | |
|---|---|---|
| Method + route | PATCH /v1/warmup-settings/{emailAccountId} | PATCH /v2/workspaces/{workspaceId}/accounts/{id}/warmup/settings |
| Key permission (scope) | any key | warmup:manage |
| Rate bucket | 20/min shared | write |
| Plan needed | some fields needed an entitlement | some sections are paid plan features (marked in the request body table below) |
What changed
- Unknown fields are rejected with
400 invalid_request. If you still send an old name (maxSendingLimit,timeZone,timeSlots,strategy,googleVolume,upcomingContentConfig, …), the whole request fails. Remove or rename every old field. timeSlots→schedule. You must send all 7 days every time (the old API let you send only the days you changed). Day numbers moved: old0= Sunday, new0= Monday. See the worked example below.- ESP split:
googleVolume/microsoftVolume/othersVolume→espMode: "CUSTOM"+espGooglePct/espMicrosoftPct/espOthersPct. - Reply rate:
replyRatealone now does nothing. SendreplyRateMode: "CUSTOM"together withreplyRate. SendreplyRateMode: "LEVEL"to go back to automatic. - Content:
upcomingContentConfig { industry, topics }→contentMode: "industry_topic"+ top-levelindustry+topics(at least 1 topic now). strategy,warmUpInitialSendingLimit,increaseEmailsByNumberare gone. The ramp is automatic and starts at 5 per day.
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
All fields are optional.
| New field | Type | Required | Allowed values / limits | What it means | Old field |
|---|---|---|---|---|---|
warmupMaxLimit | integer | no | min 5, max your plan's maxWarmupPerAccount | Maximum daily warmup sends. The ramp climbs toward it. Above the plan cap → 400 invalid_request. | maxSendingLimit (was 0–100) |
timezone | string | no | a real IANA name, e.g. America/New_York | Timezone of the schedule. | timeZone |
schedule | object[] | no | 7 to 14 rows; see rules below | Weekly sending windows. Replaces the whole schedule. Paid plan feature. | timeSlots |
schedule[].dayOfWeek | integer | yes | 0 = Monday … 6 = Sunday | Day of week. | timeSlots[].day (0 = Sunday) |
schedule[].slotIndex | integer | no | 0 or 1, default 0 | Slot number within the day, in time order. | - |
schedule[].weight | integer | no | 1–100, default 100 | Share (%) of the day's volume. The slots of an enabled day must add up to 100. | - |
schedule[].enabled | boolean | yes | - | Send on this day. Must be the same for both slots of a day. | timeSlots[].isEnabled |
schedule[].startTime | string | yes | "HH:MM" | Window start. | fromHour + fromMinute |
schedule[].endTime | string | yes | "HH:MM", after startTime | Window end. | toHour + toMinute |
replyRateMode | string | no | LEVEL, CUSTOM | LEVEL = automatic reply rate that follows the daily limit. CUSTOM = fixed replyRate. Paid plan feature. | - |
replyRate | integer | only with replyRateMode: "CUSTOM" | 0–65, and not above your plan's replyRateCap | Fixed reply rate (%). Ignored unless mode is CUSTOM. | replyRate |
espMode | string | no | AUTO, CUSTOM | AUTO = we choose the ESP mix. CUSTOM = you set the three shares. CUSTOM needs Growth plan or higher. | - (implied by sending the three volumes) |
espGooglePct | integer | with CUSTOM | 0–100 | Share (%) sent to Google mailboxes. | googleVolume (was 1–98) |
espMicrosoftPct | integer | with CUSTOM | 0–100 | Share (%) sent to Microsoft mailboxes. | microsoftVolume (was 1–98) |
espOthersPct | integer | with CUSTOM | 0–100 | Share (%) sent to other ESPs. | othersVolume (was 1–98) |
language | string | no | English, Spanish, French, German, Portuguese, Chinese, Japanese, Arabic (one of 12 values - full list in the new docs) | Language of warmup emails. Paid plan feature. | warmupLanguage |
contentMode | string | no | default, industry_topic, custom_prompt | default = general content. industry_topic needs industry and 1+ topics. custom_prompt needs customPrompt. Non-default modes are a paid plan feature. | - (implied by upcomingContentConfig) |
industry | string | with industry_topic | SaaS, Ecommerce/Retail, B2B Services, Marketing/Advertising, Real Estate, Finance/Fintech (one of 15 values - full list in the new docs) | Industry the content is written for. | upcomingContentConfig.industry |
topics | string[] | with industry_topic | up to 5; each one of about 130 values, e.g. Process Optimization, Digital Transformation, Lead Generation, Customer Retention, Industry News - full list in the new docs | Topics for content. Same values as the old API. | upcomingContentConfig.topics |
customPrompt | string | with custom_prompt | max 2000 characters | Your own prompt for generating warmup emails. | - |
templateLabelIds | array of integers | no | up to 10 unique template label ids from this workspace | Template labels (shown as "groups" in the UI) this mailbox draws templates from (replaces the current selection). [] removes it. Growth plan and above (templatesAllowed); Free and Starter get 403 forbidden. | - |
templateRatioPercent | integer | no | 0–100 | Chance (%) that one send uses a template instead of AI content. | - |
senderName | string | no | - | Sender name on warmup emails. | - |
dkimSelector | string | no | letters, digits, -, _ | Custom DKIM selector, e.g. mail. Empty = try common selectors. | - |
warmupFolder | string | no | - | Folder warmup emails are filed into. | - |
Old fields you must remove (sending them now fails with 400 invalid_request): strategy, warmUpInitialSendingLimit, increaseEmailsByNumber, timeZone, timeSlots, warmupLanguage, upcomingContentConfig, googleVolume, microsoftVolume, othersVolume, maxSendingLimit.
Schedule rules (a broken schedule is rejected with 400 invalid_request)
- Every
dayOfWeekfrom 0 to 6 must be present. Send 7 rows (one slot per day) or up to 14 rows (two slots per day). startTimemust be beforeendTimeon every row, disabled days too. A window cannot cross midnight.- On an enabled day: each slot is at least 2 hours, and the day's slots total at least 6 hours.
- With two slots, slot
1starts more than 30 minutes after slot0ends, and the two weights add up to 100. - The old API accepted any window length. Old windows shorter than 6 hours on an enabled day are now rejected; widen them.
ESP split rules
- If you send any of
espGooglePct,espMicrosoftPct,espOthersPct, send all three, and they must add up to 100. Otherwise 400invalid_request. - To return to automatic, send
"espMode": "AUTO".
Converting old timeSlots to new schedule
- Call "Get warmup settings" and keep its
schedule(the new call needs all 7 days; the old call let you send only some). - For each old slot, compute the new day:
dayOfWeek = (day + 6) % 7. Old Sunday0→ new6. Old Monday1→ new0. Old Saturday6→ new5. - Build times as two-digit
"HH:MM":fromHour: 9, fromMinute: 0→"09:00". - Copy
isEnabledtoenabled. LeaveslotIndexout (defaults to 0) andweightout (defaults to 100) for one slot per day. - Replace those days in the schedule from step 1 and send all 7 rows.
Old body (change Monday and Friday, turn off Sunday):
{
"timeZone": "America/New_York",
"timeSlots": [
{ "day": 0, "fromHour": 9, "fromMinute": 0, "toHour": 17, "toMinute": 0, "isEnabled": false },
{ "day": 1, "fromHour": 8, "fromMinute": 30, "toHour": 17, "toMinute": 30, "isEnabled": true },
{ "day": 5, "fromHour": 9, "fromMinute": 0, "toHour": 15, "toMinute": 0, "isEnabled": true }
]
}New body (the other four days copied from "Get warmup settings"):
{
"timezone": "America/New_York",
"schedule": [
{ "dayOfWeek": 0, "enabled": true, "startTime": "08:30", "endTime": "17:30" },
{ "dayOfWeek": 1, "enabled": true, "startTime": "09:00", "endTime": "17:00" },
{ "dayOfWeek": 2, "enabled": true, "startTime": "09:00", "endTime": "17:00" },
{ "dayOfWeek": 3, "enabled": true, "startTime": "09:00", "endTime": "17:00" },
{ "dayOfWeek": 4, "enabled": true, "startTime": "09:00", "endTime": "15:00" },
{ "dayOfWeek": 5, "enabled": false, "startTime": "09:00", "endTime": "17:00" },
{ "dayOfWeek": 6, "enabled": false, "startTime": "09:00", "endTime": "17:00" }
]
}Old Monday (day: 1) became dayOfWeek: 0. Old Friday (day: 5) became dayOfWeek: 4. Old Sunday (day: 0) became dayOfWeek: 6. Friday's 6-hour window is the shortest allowed on an enabled day.
The same conversion in JavaScript:
function toNewSchedule(currentSchedule, oldTimeSlots) {
const pad = (n) => String(n).padStart(2, "0");
const byDay = new Map(
currentSchedule.map((row) => [row.dayOfWeek, [row]])
);
for (const s of oldTimeSlots) {
const dayOfWeek = (s.day + 6) % 7; // old 0 = Sunday, new 0 = Monday
byDay.set(dayOfWeek, [{
dayOfWeek,
enabled: s.isEnabled,
startTime: `${pad(s.fromHour)}:${pad(s.fromMinute)}`,
endTime: `${pad(s.toHour)}:${pad(s.toMinute)}`,
}]);
}
return [...byDay.values()].flat();
}Example request (new)
curl -X PATCH "$TI_BASE_URL/v2/workspaces/42/accounts/123/warmup/settings" \
-H "Authorization: Bearer ti_ws_your_key" \
-H "Content-Type: application/json" \
-d '{
"warmupMaxLimit": 40,
"timezone": "America/New_York",
"replyRateMode": "CUSTOM",
"replyRate": 30,
"espMode": "CUSTOM",
"espGooglePct": 60,
"espMicrosoftPct": 30,
"espOthersPct": 10,
"language": "English",
"contentMode": "industry_topic",
"industry": "SaaS",
"topics": ["Digital Transformation", "Industry News"]
}'Example request (old)
curl -X PATCH "https://lupus-edge.trulyinbox.com/v1/warmup-settings/123" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"maxSendingLimit": 40,
"timeZone": "America/New_York",
"replyRate": 30,
"googleVolume": 60,
"microsoftVolume": 30,
"othersVolume": 10,
"warmupLanguage": "English",
"upcomingContentConfig": {
"industry": "SaaS",
"topics": ["Digital Transformation", "Industry News"]
}
}'Response (new)
200 OK. The body is the same as "Get warmup settings" (new), showing the saved values.
{
"data": {
"warmupMaxLimit": 40,
"maxWarmupPerAccount": 50,
"replyRateCap": 65,
"espMode": "CUSTOM",
"espGooglePct": 60,
"espMicrosoftPct": 30,
"espOthersPct": 10,
"language": "English",
"industry": "SaaS",
"topics": ["Digital Transformation", "Industry News"],
"timezone": "America/New_York",
"schedule": [
{ "dayOfWeek": 0, "slotIndex": 0, "weight": 100, "enabled": true, "startTime": "08:30", "endTime": "17:30" }
],
"templateLabels": [],
"templatePool": { "count": 0, "templates": [] },
"templateRatioPercent": 0
},
"meta": {
"request_id": "req_6e0b2d19",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}(Shortened: the real response has every field from "Get warmup settings", and all 7 schedule days.)
Response (old)
Same shape as "Get warmup settings" (old).
Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | An unknown or old field name; a value out of range; a broken schedule; ESP shares that do not add up to 100; CUSTOM reply mode without replyRate; industry_topic without industry or topics; warmupMaxLimit or replyRate above your plan cap. | Read error.message and error.details, fix the body. Do not retry unchanged. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong or revoked. | Check the Authorization: Bearer header. |
| 403 | insufficient_scope | Key has no warmup:manage scope. | Add the scope to the key. |
| 403 | workspace_forbidden | Key cannot access this workspace. | Use a key for this workspace. |
| 403 | forbidden | Your plan does not include a section you changed (custom ESP, schedule, language, content, templates, reply rate), or the key's user is below editor role. | Upgrade the plan, or remove that field. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 404 | not_found | No account with this id in this workspace, or a templateLabelIds entry not found in this workspace. | Check the ids. |
| 409 | conflict | Another schedule update ran at the same time. | Retry once. |
| 429 | rate_limit_exceeded | Write bucket is empty. | Wait error.retry_after seconds. |
Start warmup
Starts warmup on a mailbox for the first time. Use "Resume warmup" instead for a mailbox you paused, or one the system suspended.
| Old API | New API | |
|---|---|---|
| Method + route | POST /v1/warmup-settings/{emailAccountId}/start | POST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/enable |
| Key permission (scope) | any key | warmup:manage |
| Rate bucket | 20/min shared | write |
| Plan needed | - | - (the number of warming mailboxes is capped by plan) |
What changed
- Renamed from
starttoenable. There is no body. - The response is the full email account object in
data(the old call returned an empty 200). - Enable checks DNS (SPF and MX, plus DKIM on a custom domain) and the mailbox send/receive check first.
409 mailbox_verification_pendingmeans "wait, it will start by itself". Stop retrying and poll "Get warmup status".- For a paused or suspended mailbox, enable fails with 400
invalid_request. Call "Resume warmup". - You often do not need this call at all: after connect, warmup starts by itself once the checks pass.
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 POST "$TI_BASE_URL/v2/workspaces/42/accounts/123/warmup/enable" \
-H "Authorization: Bearer ti_ws_your_key"Example request (old)
curl -X POST "https://lupus-edge.trulyinbox.com/v1/warmup-settings/123/start" \
-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": "RUNNING",
"warmupPausedReason": null,
"warmupMaxLimit": 40,
"warmupCurrentLimit": 5,
"warmupStartDate": "2026-09-29T10:00:00.000Z",
"todaySent": 0,
"todayReceived": 0
},
"meta": {
"request_id": "req_3d5c8e21",
"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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 400 | invalid_request | Warmup is already running; the mailbox is disconnected; the mailbox is suspended (use resume); no sending day is enabled; warmupMaxLimit is above the plan cap. | Read error.message. Reconnect, call resume, or fix settings. |
| 400 | mailbox_verification_failed | The mailbox failed the send-and-receive check. | Fix the mailbox, then call enable again. |
| 401 | unauthorized / invalid_api_key | Key missing, wrong or revoked. | Check the Authorization: Bearer header. |
| 403 | insufficient_scope | Key has no warmup:manage scope. | Add the scope to the key. |
| 403 | workspace_forbidden | Key cannot access this workspace. | Use a key for this workspace. |
| 403 | warmup_limit_reached | Your plan already warms the maximum number of mailboxes. | Pause another mailbox, or upgrade. |
| 403 | forbidden | Required DNS records (SPF and MX, plus DKIM on a custom domain) are not passing; or the key's user is below editor role. | Fix DNS, run the DNS re-check, then retry. |
| 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. |
| 409 | mailbox_verification_pending | The send/receive check is still running. | Do not retry. Warmup starts by itself when the check passes; poll "Get warmup status". |
| 409 | conflict | The mailbox is still finishing a reconnect, or a bulk action is running on it. | Wait a moment and retry. |
| 429 | rate_limit_exceeded | Write bucket is empty. | Wait error.retry_after seconds. |