Docs
Migrating from v1Deliverability & reports

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.

DNS records

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. It replaces the old DNS health check.

This call only reads stored values. Nothing is looked up again and nothing is changed. The old endpoint did a live DNS lookup; the new one does not.

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

What changed

  • The old spf / dkim / dmarc / mx strings (pass, fail, unknown) are gone. Use fields[] for pass/fail, and spfData, dkimData, dmarcData, mxRecordData for the actual records.
  • New per-zone blacklist detail in domainBlacklistData and ipBlacklistData.
  • cachedAt is replaced by recordsRefreshedAt.
  • data can be null. It means the domain has not been checked yet. Treat it as "pending", not as "clean" and not as "failed".
  • Inside the records, null also means "never checked". It is different from isValid: false, which means "the domain does not publish this record". Never turn null into false.
  • It no longer does a live lookup. Values come from the last check (at connect, the automatic daily check, or a refresh). To force a fresh check, call Refresh the setup score, then call this endpoint.
  • There is no overall score here. For the 0–100 total and its colour band, call Setup score.

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/dns" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

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

Response (new) - 200 OK. data is either the object below or null (not checked yet).

New field (inside data)TypeWhat it meansOld field
domainstringThe mailbox's domain.-
fieldsarrayOne row per check.spf, dkim, dmarc, mx
fields[].keystringspf, dkim, dmarc, mx, domainBlacklist, ipBlacklist.-
fields[].labelstringHuman-readable name.-
fields[].scorenumberPoints earned, 0 to maxScore. score === maxScore = pass; 0 = miss.pass / fail
fields[].maxScorenumberFull weight: SPF 29, DKIM 18, domain blacklist 18, DMARC 15, IP blacklist 11, MX 9.-
spfDataobject or nullRaw SPF: { isValid, spfResults }. null = never resolved.-
dmarcDataobject or nullRaw DMARC: { isValid, dmarcResults }. null = never resolved.-
dkimDataobject or nullRaw DKIM: { isValid, dkimRecord, selector }. selector is null when no selector answered.-
mxRecordDataobject or nullMX hosts, lowest priority first: { isValid, mxRecords }.-
domainBlacklistDataobject or nullPer-zone domain blacklist result. A zone in failed could not be checked. Empty listed with non-empty failed means "unknown", not "clean".-
ipBlacklistDataobject or nullPer-zone IP blacklist result for ipAddress. Only filled for SMTP/IMAP mailboxes; Google and Microsoft OAuth mailboxes do not own their sending IP.-
ipAddressstring or nullThe IPv4 address checked against IP blacklists.-
recordsRefreshedAtdate-time or nullWhen the DNS records were last fully resolved.cachedAt
{
  "data": {
    "domain": "acme.com",
    "fields": [
      { "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": 11, "maxScore": 11 }
    ],
    "spfData": { "isValid": true, "spfResults": "v=spf1 include:_spf.google.com ~all" },
    "dmarcData": { "isValid": false, "dmarcResults": null },
    "dkimData": { "isValid": true, "dkimRecord": "v=DKIM1; k=rsa; p=MIIBIjANBgkq...", "selector": "google" },
    "mxRecordData": { "isValid": true, "mxRecords": [{ "exchange": "aspmx.l.google.com", "priority": 1 }] },
    "domainBlacklistData": { "listed": [], "failed": [] },
    "ipBlacklistData": null,
    "ipAddress": null,
    "recordsRefreshedAt": "2026-09-29T02:00:14.000Z"
  },
  "meta": {
    "request_id": "req_4c8e12aa",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

The inner shape of spfResults, mxRecords, listed and failed is not fixed in the spec. The values above are illustrative; read them defensively.

Not checked yet:

{
  "data": null,
  "meta": {
    "request_id": "req_4c8e12ab",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "emailAccountId": 456,
  "spf": "pass",
  "dkim": "pass",
  "dmarc": "pass",
  "mx": "pass",
  "cachedAt": "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 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.
429rate_limit_exceededRead bucket is used up.Wait error.retry_after seconds, then retry.

Account deliverability

Returns the deliverability, bounce and spam rates for one mailbox over the last 30 days.

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

What changed

  • The method is now GET. There is no request body.
  • You can no longer choose dates. startDate and endDate are gone; the window is always the last 30 days (from midnight UTC 30 days ago until now).
  • The esps filter is gone, and so is the per-ESP split (ESP = email provider like Gmail or Outlook). There are no more gmail, outlook, other objects.
  • The rate is calculated differently. Old totalDeliverabilityRate compared inbox with spam. New deliverabilityRate is the share of sent emails that did not bounce: (sent − bounced) / sent × 100. Do not compare old and new numbers directly.
  • New bounceRate and spamRate. All rates are percentages from 0 to 100, not rounded.
  • A mailbox with no sends in the window returns zeros, not a 404.

Path and query parameters

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

Request body - No body. The old body fields startDate, endDate and esps are removed.

Example request (new)

curl -X GET "$TI_BASE_URL/v2/workspaces/123/accounts/456/deliverability" \
  -H "Authorization: Bearer ti_ws_your_key"

Example request (old)

curl -X POST "https://lupus-edge.trulyinbox.com/v1/deliverability-score/456" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-09-01",
    "endDate": "2026-09-29",
    "esps": ["gmail", "outlook", "other"]
  }'

Response (new) - 200 OK

New field (inside data)TypeWhat it meansOld field
accountIdnumberThe email account id.emailAccountId
emailAddressstringThe mailbox address.-
deliverabilityRatenumber(sent − bounced) / sent × 100. 0 when nothing was sent.totalDeliverabilityRate (different formula)
bounceRatenumberbounced / sent × 100.-
spamRatenumberEmails that landed in spam, as a percentage of sent.- (old had totalSpamInboxCount)
sentnumberWarmup emails sent in the window.totalSentCount

The old totalInboxCount, totalSpamInboxCount, gmail, outlook and other fields have no replacement.

{
  "data": {
    "accountId": 456,
    "emailAddress": "jane@acme.com",
    "deliverabilityRate": 98.4,
    "bounceRate": 1.6,
    "spamRate": 3.2,
    "sent": 1250
  },
  "meta": {
    "request_id": "req_0b77d3e9",
    "timestamp": "2026-09-29T10:00:00.000Z"
  }
}

Response (old)

{
  "emailAccountId": 456,
  "totalDeliverabilityRate": 88,
  "totalSentCount": 1500,
  "totalInboxCount": 1320,
  "totalSpamInboxCount": 180,
  "gmail": { "deliverabilityRate": 92, "sentCount": 500, "inboxCount": 460, "spamCount": 40 },
  "outlook": { "deliverabilityRate": 92, "sentCount": 500, "inboxCount": 460, "spamCount": 40 },
  "other": { "deliverabilityRate": 92, "sentCount": 500, "inboxCount": 460, "spamCount": 40 }
}

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 analytics: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.
429rate_limit_exceededRead bucket is used up.Wait error.retry_after seconds, then retry.