Warmup

Warmup endpoints report on the health of your mailboxes and the automated inbox-placement emails Warmerly sends and receives between accounts. Use them to build dashboards, alert on score drops, or list the individual warmup emails sent for an account.

Get warmup stats

Returns a point-in-time summary across your accounts: how many are active, aging, or paused, how many warmup emails have gone out today, and the average health score.

X-Project-Id is optional here — omit it to get stats across every project in your current workspace, or pass it to scope the numbers to a single project.

curl https://app.warmerly.com/api/v1/warmup/stats \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Project-Id: 8f14e45f-ceea-4c6a-8c8d-6b1a5b5c9c1a"

{
  "activeAccounts": 12,
  "agingAccounts": 3,
  "pausedAccounts": 1,
  "todaySent": 84,
  "todayScheduled": 96,
  "avgHealthScore": 87
}

Get warmup trends

Returns a daily time series plus a current-vs-previous-window summary, suitable for charting score and inbox-placement rate over time. Backed by daily health_snapshots rows, aggregated across the accounts you have access to.

X-Project-Id is optional, same as /warmup/stats — pass it to scope to one project.

curl "https://app.warmerly.com/api/v1/warmup/trends?days=30" \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Project-Id: 8f14e45f-ceea-4c6a-8c8d-6b1a5b5c9c1a"

{
  "range": { "days": 30, "from": "2026-06-03", "to": "2026-07-02" },
  "series": [
    { "date": "2026-06-03", "sent": 41, "inbox": 37, "spam": 3, "bounce": 1, "score": 82 },
    { "date": "2026-06-04", "sent": 45, "inbox": 42, "spam": 2, "bounce": 1, "score": 84 }
  ],
  "summary": {
    "avgScore": 87,
    "avgScorePrev": 81,
    "avgScoreDelta": 6,
    "inboxRate": 92,
    "inboxRatePrev": 88,
    "inboxRateDelta": 4,
    "sentTotal": 1240,
    "sentTotalPrev": 1105
  }
}

series is ordered ascending by date and covers the requested window only. summary compares the requested window (cur) against the equal-length window immediately before it (prev); any rate is null when there's no data to divide by. inboxRate is inbox / (inbox + spam + bounce), expressed as a whole-number percentage.

List warmup jobs

Returns individual warmup emails (a "job" is one email sent from one warmed mailbox to another), most recent first. This endpoint doesn't take X-Project-Id — filter by account_id to scope results to a specific mailbox.

curl "https://app.warmerly.com/api/v1/warmup/jobs?account_id=1c2d3e4f-...&status=processed&limit=20" \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "jobs": [
    {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "senderAccountId": "1c2d3e4f-1111-4a2b-8c3d-4e5f6a7b8c9d",
      "recipientAccountId": "2d3e4f5a-2222-4a2b-8c3d-4e5f6a7b8c9d",
      "scheduledAt": "2026-07-02T08:00:00.000Z",
      "sentAt": "2026-07-02T08:00:42.000Z",
      "status": "processed",
      "subject": "Re: quick question about the roadmap",
      "deliveredFolder": "inbox",
      "wasOpened": true,
      "wasReplied": false,
      "emailType": "reply"
    }
  ]
}

Per-account health and job history

Two account-scoped endpoints give you the same data filtered to a single mailbox. Both take the account ID from the URL, not X-Project-Id.

Get an account's health snapshots

curl "https://app.warmerly.com/api/v1/accounts/1c2d3e4f-.../health?days=30" \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "health": [
    {
      "id": "b3e1c9a0-....",
      "accountId": "1c2d3e4f-....",
      "date": "2026-07-02",
      "sentCount": 22,
      "inboxCount": 20,
      "spamCount": 1,
      "bounceCount": 1,
      "replyCount": 3,
      "openCount": 17,
      "score": 89,
      "trend": "up",
      "spamScore": 0,
      "computedAt": "2026-07-02T00:15:00.000Z"
    }
  ]
}

health is ordered most recent first. trend is up, flat, or down relative to the previous day's score.

Get an account's warmup job history

Returns the last 100 jobs (sent or received) for the account, plus a 30-day daily summary. Returns 404 if the account doesn't exist.

curl "https://app.warmerly.com/api/v1/accounts/1c2d3e4f-.../warmup-jobs" \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "jobs": [
    {
      "id": "9b1deb4d-....",
      "scheduledAt": "2026-07-02T08:00:00.000Z",
      "sentAt": "2026-07-02T08:00:42.000Z",
      "status": "processed",
      "senderAccountId": "1c2d3e4f-....",
      "recipientAccountId": "2d3e4f5a-....",
      "subject": "Re: quick question about the roadmap",
      "deliveredFolder": "inbox",
      "wasOpened": true,
      "wasReplied": false,
      "emailType": "reply"
    }
  ],
  "dailySummary": [
    { "day": "2026-07-02", "sent": 22, "received": 19, "inbox": 20, "spam": 1 }
  ]
}

dailySummary covers the trailing 30 days: sent and received count jobs where the account was sender/recipient respectively; inbox/spam count only processed jobs the account sent that landed in each folder.

Pause and resume warmup on an account

Warmup only runs against accounts with status = active or aging. Pausing an account stops it from being scheduled as a sender or recipient in future warmup jobs.

POST /accounts/{id}/pause
POST /accounts/{id}/resume

Both take no request body and return 404 if the account doesn't exist.

curl -X POST https://app.warmerly.com/api/v1/accounts/1c2d3e4f-.../pause \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{ "ok": true }

resume sets the account back to active, clears needsReconnect and disconnectReason, and resets consecutiveFailures to 0:

curl -X POST https://app.warmerly.com/api/v1/accounts/1c2d3e4f-.../resume \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{ "ok": true }

Mailbox health alerts

The last 50 mailbox-health alerts raised for your account, newest first. These are the same events that trigger a health email, so polling this is the pull equivalent of webhooks for anyone who would rather not run an endpoint.

{
  "alerts": [
    {
      "id": "c3f1a2b4-5d6e-4f70-8a91-b2c3d4e5f607",
      "accountId": "3a6f9e2e-4b7a-4e9a-9b1d-6e3a2f8c1a10",
      "kind": "score_drop",
      "severity": "warning",
      "title": "Warmup health dropped for jane@yourdomain.com",
      "body": "Health score fell from 82 to 61 over the last 24 hours.",
      "scoreBefore": 82,
      "scoreAfter": 61,
      "sentAt": "2026-09-11T06:02:00.000Z",
      "createdAt": "2026-09-11T06:01:58.000Z"
    }
  ]
}

severity is info, warning or critical. sentAt is when the notification went out (null if it has not been sent), as opposed to createdAt, when the condition was detected.

Is warmup actually running?

Whether Warmerly's warmup workers are alive. A plain authenticated caller gets the derived flag:

{ "ok": true, "healthy": true }

healthy is true when the freshest worker heartbeat is under 10 minutes old. It is a platform-level answer, not a statement about your mailboxes: healthy: true with nothing sending means the problem is your campaign or mailbox configuration, and GET /campaigns/{id}/readiness will say which. Staff callers additionally get lastTick per worker.

POST /warmup/run exists but is ops-only: it triggers a planner/dispatcher pass across every workspace on the platform, so it returns 404 for a customer key. Warmup runs continuously on its own; there is nothing to trigger.

Errors

An account ID that doesn't exist returns 404 on any of the endpoints above:

{ "error": { "code": "not_found", "message": "not_found", "details": null } }

Missing or invalid X-Api-Key returns 401, following the same shape described in Authentication.