Placement tests

API referenceAccounts

From the Accounts API reference. Requests use the base URL https://app.warmerly.com/api/v1 and an API key, see Authentication.

text

GET  /accounts/{id}/placement
POST /accounts/{id}/placement

GET lists this account's 10 most recent placement tests, newest first, with a summary:

json

{
  "tests": [
    {
      "id": "6d2f0b1a-9c4e-4f77-bb31-2a9e7c4d8e55",
      "accountId": "3a6f9e2e-4b7a-4e9a-9b1d-6e3a2f8c1a10",
      "startedAt": "2026-09-10T09:00:00.000Z",
      "completedAt": "2026-09-10T09:01:04.000Z",
      "status": "done",
      "score": 82,
      "details": { }
    }
  ],
  "summary": {
    "latestScore": 82,
    "latestStatus": "done",
    "latestStartedAt": "2026-09-10T09:00:00.000Z",
    "latestDegraded": false,
    "trendDelta": 6
  }
}

status is pending, running, done or failed. trendDelta is the score change against the previous comparable test, or null when there is nothing fair to compare with. latestDegraded is true when the latest test was measured against Warmerly's own warmup mailboxes rather than real seed inboxes. Its score is not a placement result and is not comparable with a clean one. Tests recorded before this flag existed also read as degraded.

POST sends live email and spends quota. It dispatches probe messages from this mailbox to seed addresses and debits one of your monthly placement tests (counted per user, as in Usage & limits). Out of allowance returns 402 with error.code quota_exhausted and details carrying used, limit, upgradeUrl and, when credits can cover it, a topUp offer. The charge is taken before the run and handed back if the run fails, which returns 400 bad_request. The response is { "test": { … } }. The call waits at least 30 seconds for delivery before responding, so expect it to take that long or more.

Was this page helpful?

Placement tests

More from Accounts