Docs
Migrating from v1Deliverability & reports

Deliverability & reports

Setup score, DNS, deliverability, dashboards and stats: old routes and their /v2 replacements.

These endpoints tell you how healthy a mailbox's domain setup is and how its warmup emails are performing, for one mailbox.


Setup score (per account)

Returns the 0–100 setup score for one mailbox and the checks behind it. Call it to show a health badge or a setup checklist. The value is read from the last stored check; nothing is re-checked.

Old APINew API
Method + routeGET /v1/setup-score/{emailAccountId}GET /v2/workspaces/{workspaceId}/accounts/{id}/setup-score
Key permission (scope)any keyaccounts:read
Rate bucket20/min sharedread
Plan needed--

What changed

  • emailAccountScore is now score. It can be null, which means the domain has never been scored. null is not the same as 0.
  • The spf, dkim, dmarc, mx booleans and the ipBlacklist / domainBlacklist counts are gone. They are replaced by one items array with a score and maxScore per check.
  • New band (green, yellow, red) gives you a ready colour for the whole score. It is null when the domain was never scored.
  • updatedAt and manualLastRefreshedAt are replaced by dnsCheckedAt.
  • For the per-zone blacklist detail and the raw DNS records, call DNS records.

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 GET "$TI_BASE_URL/v2/workspaces/123/accounts/456/setup-score" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X GET "https://lupus-edge.trulyinbox.com/v1/setup-score/456" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new) - 200 OK

New field (inside data)TypeWhat it meansOld field
accountIdnumberThe email account id.emailAccountId
emailAddressstringThe mailbox address.-
scorenumber or nullSetup score, 0–100. It is the sum of items[].score. null = never scored.emailAccountScore
bandgreen | yellow | red or nullColour band for the whole score. Items have no band of their own. null when the domain was never scored (same time score is null).-
itemsarrayOne row per check. Empty when the domain was never scored.spf, dkim, dmarc, mx, ipBlacklist, domainBlacklist
items[].keystringStable id: spf, dkim, dmarc, mx, domainBlacklist, ipBlacklist.-
items[].labelstringHuman-readable name, for example "SPF record".-
items[].scorenumberPoints this check earned, from 0 to maxScore.-
items[].maxScorenumberFull weight of this check: SPF 29, DKIM 18, domain blacklist 18, DMARC 15, IP blacklist 11, MX 9. They add up to 100.-
dnsCheckedAtstring (date-time) or nullWhen the DNS records were last checked. null = never.updatedAt

How to read an item: score === maxScore is a pass, score === 0 is a miss. A check that does not apply still costs its full weight. For example, a personal-domain mailbox can reach at most 82, and a mailbox with no known sending IP loses the 11 IP-blacklist points.

{
  "data": {
    "accountId": 456,
    "emailAddress": "jane@acme.com",
    "score": 82,
    "band": "green",
    "items": [
      { "key": "spf", "label": "SPF record", "score": 29, "maxScore": 29 },
      { "key": "dkim", "label": "DKIM record", "score": 18, "maxScore": 18 },
      { "key": "dmarc", "label": "DMARC record", "score": 0, "maxScore": 15 },
      { "key": "mx", "label": "MX records", "score": 9, "maxScore": 9 },
      { "key": "domainBlacklist", "label": "Domain blacklist", "score": 18, "maxScore": 18 },
      { "key": "ipBlacklist", "label": "IP blacklist", "score": 8, "maxScore": 11 }
    ],
    "dnsCheckedAt": "2026-09-29T02:00:14.000Z"
  },
  "meta": {
    "request_id": "req_7d2a91c4",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "emailAccountId": 456,
  "emailAccountScore": 86,
  "spf": true,
  "dkim": true,
  "dmarc": false,
  "mx": true,
  "ipBlacklist": { "listed": 2, "notListed": 45 },
  "domainBlacklist": { "listed": 2, "notListed": 45 },
  "updatedAt": "2026-04-08T10:30:00.000Z",
  "manualLastRefreshedAt": "2026-04-08T10:30:00.000Z"
}

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyKey missing, wrong, or revoked.Check the Authorization: Bearer header and the key.
403insufficient_scopeKey does not have accounts:read.Add the scope to the key.
403workspace_forbiddenKey cannot access this workspace.Use the right workspaceId or key.
404not_foundNo email account with this id in this workspace.Check the id; the account may be deleted.
429rate_limit_exceededRead bucket is used up.Wait error.retry_after seconds, then retry.

Refresh the setup score

Runs a fresh check of the mailbox's domain right now and returns the new setup score. Call it after the user fixes a DNS record.

Old APINew API
Method + routePOST /v1/setup-score/{emailAccountId}/refreshPOST /v2/workspaces/{workspaceId}/accounts/{id}/setup-score/refresh
Key permission (scope)any keyaccounts:write
Rate bucket20/min sharedwrite
Plan needed--

What changed

  • The path moved under the workspace. It needs the accounts:write scope, not accounts:read.
  • You can refresh a mailbox once every 3 hours. The 3 hours count from the last check of any kind, including the automatic daily check and the check at connect time. An earlier call returns 429 recheck_too_soon.
  • While a check is already running for the mailbox, the call returns 409 check_in_progress.
  • To avoid recheck_too_soon, wait at least 3 hours after the last check (dnsCheckedAt on Setup score shows the last DNS check).
  • The response has the same shape as Setup score.
  • If a DNS lookup fails at the resolver (a timeout, for example), the old value is kept. A short DNS outage does not lower the score.
  • A personal key whose owner has only viewer access to the workspace is refused with 403.

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/123/accounts/456/setup-score/refresh" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/setup-score/456/refresh" \
  -H "X-Api-Key: YOUR_API_KEY"

Response (new) - 200 OK. Same fields as Setup score.

{
  "data": {
    "accountId": 456,
    "emailAddress": "jane@acme.com",
    "score": 97,
    "band": "green",
    "items": [
      { "key": "spf", "label": "SPF record", "score": 29, "maxScore": 29 },
      { "key": "dkim", "label": "DKIM record", "score": 18, "maxScore": 18 },
      { "key": "dmarc", "label": "DMARC record", "score": 15, "maxScore": 15 },
      { "key": "mx", "label": "MX records", "score": 9, "maxScore": 9 },
      { "key": "domainBlacklist", "label": "Domain blacklist", "score": 18, "maxScore": 18 },
      { "key": "ipBlacklist", "label": "IP blacklist", "score": 8, "maxScore": 11 }
    ],
    "dnsCheckedAt": "2026-09-29T10:00:03.000Z"
  },
  "meta": {
    "request_id": "req_91be30f2",
    "timestamp": "2026-09-29T10:00:04.000Z"
  }
}

Response (old) - same shape as the old setup score response above.

The two new "not now" errors

  • 429 recheck_too_soon - this mailbox was checked less than 3 hours ago. The limit is per mailbox, not per key. It is not the API rate limit, so do not slow down your other calls. Do not retry in a loop. Read the current score with Setup score and try again later. This error does not carry retry_after.
  • 409 check_in_progress - a check for this mailbox is already running. You do not need to call refresh again. When the running check finishes, the new result is stored. Read it later with Setup score.

Errors you should handle

HTTPerror.codeWhen it happensWhat to do
401unauthorized / invalid_api_keyKey missing, wrong, or revoked.Check the header and the key.
403insufficient_scopeKey does not have accounts:write.Add the scope to the key.
403workspace_forbidden / forbiddenKey cannot access this workspace, or the key's owner has only viewer access.Use a key with editor access or higher.
404not_foundNo email account with this id in this workspace.Check the id.
409check_in_progressA check is already running for this mailbox.Stop. Read the setup score later.
429recheck_too_soonThe mailbox was checked less than 3 hours ago.Stop. Retry later, at least 3 hours after the last check. Keep your other calls going.
429rate_limit_exceededWrite bucket is used up.Wait error.retry_after seconds, then retry.