Docs
Migrating from v1Warmup

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 APINew API
Method + routePATCH /v1/warmup-settings/{emailAccountId}PATCH /v2/workspaces/{workspaceId}/accounts/{id}/warmup/settings
Key permission (scope)any keywarmup:manage
Rate bucket20/min sharedwrite
Plan neededsome fields needed an entitlementsome 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: old 0 = Sunday, new 0 = Monday. See the worked example below.
  • ESP split: googleVolume / microsoftVolume / othersVolume → espMode: "CUSTOM" + espGooglePct / espMicrosoftPct / espOthersPct.
  • Reply rate: replyRate alone now does nothing. Send replyRateMode: "CUSTOM" together with replyRate. Send replyRateMode: "LEVEL" to go back to automatic.
  • Content: upcomingContentConfig { industry, topics } → contentMode: "industry_topic" + top-level industry + topics (at least 1 topic now).
  • strategy, warmUpInitialSendingLimit, increaseEmailsByNumber are gone. The ramp is automatic and starts at 5 per day.

Path and query parameters

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

Request body

All fields are optional.

New fieldTypeRequiredAllowed values / limitsWhat it meansOld field
warmupMaxLimitintegernomin 5, max your plan's maxWarmupPerAccountMaximum daily warmup sends. The ramp climbs toward it. Above the plan cap → 400 invalid_request.maxSendingLimit (was 0–100)
timezonestringnoa real IANA name, e.g. America/New_YorkTimezone of the schedule.timeZone
scheduleobject[]no7 to 14 rows; see rules belowWeekly sending windows. Replaces the whole schedule. Paid plan feature.timeSlots
schedule[].dayOfWeekintegeryes0 = Monday … 6 = SundayDay of week.timeSlots[].day (0 = Sunday)
schedule[].slotIndexintegerno0 or 1, default 0Slot number within the day, in time order.-
schedule[].weightintegerno1–100, default 100Share (%) of the day's volume. The slots of an enabled day must add up to 100.-
schedule[].enabledbooleanyes-Send on this day. Must be the same for both slots of a day.timeSlots[].isEnabled
schedule[].startTimestringyes"HH:MM"Window start.fromHour + fromMinute
schedule[].endTimestringyes"HH:MM", after startTimeWindow end.toHour + toMinute
replyRateModestringnoLEVEL, CUSTOMLEVEL = automatic reply rate that follows the daily limit. CUSTOM = fixed replyRate. Paid plan feature.-
replyRateintegeronly with replyRateMode: "CUSTOM"0–65, and not above your plan's replyRateCapFixed reply rate (%). Ignored unless mode is CUSTOM.replyRate
espModestringnoAUTO, CUSTOMAUTO = we choose the ESP mix. CUSTOM = you set the three shares. CUSTOM needs Growth plan or higher.- (implied by sending the three volumes)
espGooglePctintegerwith CUSTOM0–100Share (%) sent to Google mailboxes.googleVolume (was 1–98)
espMicrosoftPctintegerwith CUSTOM0–100Share (%) sent to Microsoft mailboxes.microsoftVolume (was 1–98)
espOthersPctintegerwith CUSTOM0–100Share (%) sent to other ESPs.othersVolume (was 1–98)
languagestringnoEnglish, 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
contentModestringnodefault, industry_topic, custom_promptdefault = general content. industry_topic needs industry and 1+ topics. custom_prompt needs customPrompt. Non-default modes are a paid plan feature.- (implied by upcomingContentConfig)
industrystringwith industry_topicSaaS, 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
topicsstring[]with industry_topicup 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 docsTopics for content. Same values as the old API.upcomingContentConfig.topics
customPromptstringwith custom_promptmax 2000 charactersYour own prompt for generating warmup emails.-
templateLabelIdsarray of integersnoup to 10 unique template label ids from this workspaceTemplate 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.-
templateRatioPercentintegerno0–100Chance (%) that one send uses a template instead of AI content.-
senderNamestringno-Sender name on warmup emails.-
dkimSelectorstringnoletters, digits, -, _Custom DKIM selector, e.g. mail. Empty = try common selectors.-
warmupFolderstringno-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 dayOfWeek from 0 to 6 must be present. Send 7 rows (one slot per day) or up to 14 rows (two slots per day).
  • startTime must be before endTime on 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 1 starts more than 30 minutes after slot 0 ends, 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 400 invalid_request.
  • To return to automatic, send "espMode": "AUTO".

Converting old timeSlots to new schedule

  1. Call "Get warmup settings" and keep its schedule (the new call needs all 7 days; the old call let you send only some).
  2. For each old slot, compute the new day: dayOfWeek = (day + 6) % 7. Old Sunday 0 → new 6. Old Monday 1 → new 0. Old Saturday 6 → new 5.
  3. Build times as two-digit "HH:MM": fromHour: 9, fromMinute: 0 → "09:00".
  4. Copy isEnabled to enabled. Leave slotIndex out (defaults to 0) and weight out (defaults to 100) for one slot per day.
  5. 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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestAn 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.
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.
403forbiddenYour 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.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo account with this id in this workspace, or a templateLabelIds entry not found in this workspace.Check the ids.
409conflictAnother schedule update ran at the same time.Retry once.
429rate_limit_exceededWrite 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 APINew API
Method + routePOST /v1/warmup-settings/{emailAccountId}/startPOST /v2/workspaces/{workspaceId}/accounts/{id}/warmup/enable
Key permission (scope)any keywarmup:manage
Rate bucket20/min sharedwrite
Plan needed-- (the number of warming mailboxes is capped by plan)

What changed

  • Renamed from start to enable. 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_pending means "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

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/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

HTTPerror.codeWhen it happensWhat to do
400invalid_requestWarmup 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.
400mailbox_verification_failedThe mailbox failed the send-and-receive check.Fix the mailbox, then call enable again.
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.
403forbiddenRequired 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.
403subscription_pausedThe subscription is paused.Resume the subscription.
404not_foundNo account with this id in this workspace.Check workspaceId and id.
409mailbox_verification_pendingThe send/receive check is still running.Do not retry. Warmup starts by itself when the check passes; poll "Get warmup status".
409conflictThe mailbox is still finishing a reconnect, or a bulk action is running on it.Wait a moment and retry.
429rate_limit_exceededWrite bucket is empty.Wait error.retry_after seconds.