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 API | New API | |
|---|---|---|
| Method + route | GET /v1/dns-health/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/dns |
| Key permission (scope) | any key | accounts:read |
| Rate bucket | 20/min shared | read |
| Plan needed | - | - |
What changed
- The old
spf/dkim/dmarc/mxstrings (pass,fail,unknown) are gone. Usefields[]for pass/fail, andspfData,dkimData,dmarcData,mxRecordDatafor the actual records. - New per-zone blacklist detail in
domainBlacklistDataandipBlacklistData. cachedAtis replaced byrecordsRefreshedAt.datacan benull. It means the domain has not been checked yet. Treat it as "pending", not as "clean" and not as "failed".- Inside the records,
nullalso means "never checked". It is different fromisValid: false, which means "the domain does not publish this record". Never turnnullintofalse. - 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
| 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/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) | Type | What it means | Old field |
|---|---|---|---|
domain | string | The mailbox's domain. | - |
fields | array | One row per check. | spf, dkim, dmarc, mx |
fields[].key | string | spf, dkim, dmarc, mx, domainBlacklist, ipBlacklist. | - |
fields[].label | string | Human-readable name. | - |
fields[].score | number | Points earned, 0 to maxScore. score === maxScore = pass; 0 = miss. | pass / fail |
fields[].maxScore | number | Full weight: SPF 29, DKIM 18, domain blacklist 18, DMARC 15, IP blacklist 11, MX 9. | - |
spfData | object or null | Raw SPF: { isValid, spfResults }. null = never resolved. | - |
dmarcData | object or null | Raw DMARC: { isValid, dmarcResults }. null = never resolved. | - |
dkimData | object or null | Raw DKIM: { isValid, dkimRecord, selector }. selector is null when no selector answered. | - |
mxRecordData | object or null | MX hosts, lowest priority first: { isValid, mxRecords }. | - |
domainBlacklistData | object or null | Per-zone domain blacklist result. A zone in failed could not be checked. Empty listed with non-empty failed means "unknown", not "clean". | - |
ipBlacklistData | object or null | Per-zone IP blacklist result for ipAddress. Only filled for SMTP/IMAP mailboxes; Google and Microsoft OAuth mailboxes do not own their sending IP. | - |
ipAddress | string or null | The IPv4 address checked against IP blacklists. | - |
recordsRefreshedAt | date-time or null | When 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
| 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: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. |
| 429 | rate_limit_exceeded | Read 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 API | New API | |
|---|---|---|
| Method + route | POST /v1/deliverability-score/{emailAccountId} | GET /v2/workspaces/{workspaceId}/accounts/{id}/deliverability |
| Key permission (scope) | any key | analytics:read |
| Rate bucket | 20/min shared | read |
| Plan needed | - | - |
What changed
- The method is now
GET. There is no request body. - You can no longer choose dates.
startDateandendDateare gone; the window is always the last 30 days (from midnight UTC 30 days ago until now). - The
espsfilter is gone, and so is the per-ESP split (ESP = email provider like Gmail or Outlook). There are no moregmail,outlook,otherobjects. - The rate is calculated differently. Old
totalDeliverabilityRatecompared inbox with spam. NewdeliverabilityRateis the share of sent emails that did not bounce:(sent − bounced) / sent × 100. Do not compare old and new numbers directly. - New
bounceRateandspamRate. 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
| 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. 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) | Type | What it means | Old field |
|---|---|---|---|
accountId | number | The email account id. | emailAccountId |
emailAddress | string | The mailbox address. | - |
deliverabilityRate | number | (sent − bounced) / sent × 100. 0 when nothing was sent. | totalDeliverabilityRate (different formula) |
bounceRate | number | bounced / sent × 100. | - |
spamRate | number | Emails that landed in spam, as a percentage of sent. | - (old had totalSpamInboxCount) |
sent | number | Warmup 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
| 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 analytics: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. |
| 429 | rate_limit_exceeded | Read bucket is used up. | Wait error.retry_after seconds, then retry. |