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 API | New API | |
|---|---|---|
| Method + route | GET /v1/setup-score/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/setup-score |
| Key permission (scope) | any key | accounts:read |
| Rate bucket | 20/min shared | read |
| Plan needed | - | - |
What changed
emailAccountScoreis nowscore. It can benull, which means the domain has never been scored.nullis not the same as0.- The
spf,dkim,dmarc,mxbooleans and theipBlacklist/domainBlacklistcounts are gone. They are replaced by oneitemsarray with ascoreandmaxScoreper check. - New
band(green,yellow,red) gives you a ready colour for the whole score. It isnullwhen the domain was never scored. updatedAtandmanualLastRefreshedAtare replaced bydnsCheckedAt.- For the per-zone blacklist detail and the raw DNS records, call DNS records.
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 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) | Type | What it means | Old field |
|---|---|---|---|
accountId | number | The email account id. | emailAccountId |
emailAddress | string | The mailbox address. | - |
score | number or null | Setup score, 0–100. It is the sum of items[].score. null = never scored. | emailAccountScore |
band | green | yellow | red or null | Colour band for the whole score. Items have no band of their own. null when the domain was never scored (same time score is null). | - |
items | array | One row per check. Empty when the domain was never scored. | spf, dkim, dmarc, mx, ipBlacklist, domainBlacklist |
items[].key | string | Stable id: spf, dkim, dmarc, mx, domainBlacklist, ipBlacklist. | - |
items[].label | string | Human-readable name, for example "SPF record". | - |
items[].score | number | Points this check earned, from 0 to maxScore. | - |
items[].maxScore | number | Full weight of this check: SPF 29, DKIM 18, domain blacklist 18, DMARC 15, IP blacklist 11, MX 9. They add up to 100. | - |
dnsCheckedAt | string (date-time) or null | When 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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | Key missing, wrong, or revoked. | Check the Authorization: Bearer header and the key. |
| 403 | insufficient_scope | Key does not have accounts:read. | Add the scope to the key. |
| 403 | workspace_forbidden | Key cannot access this workspace. | Use the right workspaceId or key. |
| 404 | not_found | No email account with this id in this workspace. | Check the id; the account may be deleted. |
| 429 | rate_limit_exceeded | Read 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 API | New API | |
|---|---|---|
| Method + route | POST /v1/setup-score/{emailAccountId}/refresh | POST /v2/workspaces/{workspaceId}/accounts/{id}/setup-score/refresh |
| Key permission (scope) | any key | accounts:write |
| Rate bucket | 20/min shared | write |
| Plan needed | - | - |
What changed
- The path moved under the workspace. It needs the
accounts:writescope, notaccounts: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 (dnsCheckedAton 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
| 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/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 carryretry_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
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | Key missing, wrong, or revoked. | Check the header and the key. |
| 403 | insufficient_scope | Key does not have accounts:write. | Add the scope to the key. |
| 403 | workspace_forbidden / forbidden | Key cannot access this workspace, or the key's owner has only viewer access. | Use a key with editor access or higher. |
| 404 | not_found | No email account with this id in this workspace. | Check the id. |
| 409 | check_in_progress | A check is already running for this mailbox. | Stop. Read the setup score later. |
| 429 | recheck_too_soon | The mailbox was checked less than 3 hours ago. | Stop. Retry later, at least 3 hours after the last check. Keep your other calls going. |
| 429 | rate_limit_exceeded | Write bucket is used up. | Wait error.retry_after seconds, then retry. |
Preview mailboxes to Check import progress (sync-status)
Lists the tenant's mailboxes that are not connected yet. Use it to choose what to import.
DNS records to Account deliverability
Returns the stored SPF, DKIM, DMARC and MX records for the mailbox's domain, with the blacklist results and a score per check. Use it for a detailed domain health screen.