Tools
Deliverability tools: DNS checker for any domain, DMARC and SPF builders, header analyzer, address checker and pre-send content check. Results are not stored.
Check the email DNS records of any domain
POST /v1/tools/dns
Checks MX, SPF (with the DNS lookup count through nested includes), DKIM, DMARC, BIMI (logo and certificate reachability), MTA-STS and TLS-RPT for any domain, not only domains in this workspace. Uses DNS-over-HTTPS. Nothing is stored. Rate-limited per workspace (30 checks per minute).
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
domainrequired | string | Domain name, for example example.com. A URL or an email address is reduced to its domain. |
selectors | array of string | DKIM selectors to check (the s= tag of a DKIM-Signature). Without them, common selector names are tried. At most 20 items. |
checks | array of "mx" | "spf" | "dkim" | "dmarc" | "bimi" | "mta_sts" | "tls_rpt" | Run only these checks. Default: all. |
Responses
{
"domain": string,
"checkedAt": string,
"status": "ok" | "info" | "warning" | "error",
"mx": {
"status": "ok" | "info" | "warning" | "error",
"name": string,
"records": [string],
"findings": [{
"level": "ok" | "info" | "warning" | "error",
"code": string,
"message": string
}],
"details": any
},
"spf": {
"status": "ok" | "info" | "warning" | "error",
"name": string,
"records": [string],
"findings": [{
"level": "ok" | "info" | "warning" | "error",
"code": string,
"message": string
}],
"details": any
},
"dkim": {
"status": "ok" | "info" | "warning" | "error",
"name": string,
"records": [string],
"findings": [{
"level": "ok" | "info" | "warning" | "error",
"code": string,
"message": string
}],
"details": any
},
"dmarc": {
"status": "ok" | "info" | "warning" | "error",
"name": string,
"records": [string],
"findings": [{
"level": "ok" | "info" | "warning" | "error",
"code": string,
"message": string
}],
"details": any
},
"bimi": {
"status": "ok" | "info" | "warning" | "error",
"name": string,
"records": [string],
"findings": [{
"level": "ok" | "info" | "warning" | "error",
"code": string,
"message": string
}],
"details": any
},
"mta_sts": {
…Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Generate a DMARC record
POST /v1/tools/dmarc
Builds a DMARC TXT record from the chosen policy and options, with a plain-language explanation of each tag. Nothing is published.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
domain | string | Domain name, for example example.com. A URL or an email address is reduced to its domain. |
policyrequired | "none" | "quarantine" | "reject" | |
subdomainPolicy | "none" | "quarantine" | "reject" | null | |
pct | integer | 0 to 100. |
rua | array of string | Addresses for aggregate reports. At most 5 items. |
ruf | array of string | Addresses for failure reports. At most 5 items. |
adkim | "r" | "s" | |
aspf | "r" | "s" | |
fo | string | |
ri | integer | 3600 to 604800. |
Responses
{
"name": string or null,
"record": string,
"explanation": [string]
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Build an SPF record
POST /v1/tools/spf
Builds an SPF record from the sending providers connected to this workspace (or the providers you list), extra includes and IP addresses, and counts the DNS lookups it needs (limit 10). Providers that publish SPF on their own return-path subdomain are listed but not added unless includeSubdomainProviders is true.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
domain | string | Compare with the SPF record published for this domain. |
providers | array of string | Provider ids. Default: the sending providers connected to this workspace. At most 30 items. |
includes | array of string | At most 20 items. |
ip4 | array of string | At most 20 items. |
ip6 | array of string | At most 20 items. |
mx | boolean | |
a | boolean | |
all | "-all" | "~all" | "?all" | |
includeSubdomainProviders | boolean | Also add includes for providers that publish SPF on their own return-path subdomain. |
countLookups | boolean | Resolve includes to count DNS lookups (default true). |
Responses
{
"record": string,
"lookups": number or null,
"providers": [{
"provider": string,
"include": string or null,
"added": boolean,
"note": string
}],
"findings": [{
"level": "ok" | "info" | "warning" | "error",
"code": string,
"message": string
}],
"current": {
"domain": string,
"record": string or null,
"lookups": number
}
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Analyze email headers
POST /v1/tools/headers
Parses raw message headers: the delivery path (Received hops with the delay at each), the sending IP, SPF, DKIM and DMARC results from Authentication-Results, alignment with the From domain, and spam-filter headers. Nothing is stored.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
headersrequired | string | Raw message headers as copied from "Show original" or "View source". |
Responses
{
"summary": object,
"hops": [{
"index": number,
"from": string or null,
"by": string or null,
"with": string or null,
"ip": string or null,
"date": string or null,
"delaySeconds": number or null,
"tls": boolean
}],
"totalDelaySeconds": number or null,
"sendingIps": [string],
"originIp": string or null,
"authentication": object,
"dkimSignatures": [object],
"alignment": object,
"spam": [{
"name": string,
"value": string
}],
"findings": [{
"level": "ok" | "info" | "warning" | "error",
"code": string,
"message": string
}],
"headerCount": number
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Check email addresses
POST /v1/tools/address
For one address (email) or up to 50 (emails): syntax, whether the domain accepts email (MX), disposable domains (a small bundled list), role addresses such as info@ or admin@, and whether the address is on this workspace's suppression list. It does not connect to the recipient's mail server. Status: valid, risky, invalid, suppressed or unknown (DNS could not be reached).
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
email | string | |
emails | array of string | At most 50 items. |
Responses
{
"data": [{
"input": string,
"email": string or null,
"status": "valid" | "risky" | "invalid" | "suppressed" | "unknown",
"syntax": boolean,
"domain": string or null,
"mx": {
"found": boolean or null,
"hosts": [string],
"implicit": boolean,
"nullMx": boolean
},
"disposable": boolean,
"role": boolean,
"suppressed": {
"reason": string,
"scope": string,
"createdAt": string
},
"findings": [{ … }]
}]
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Check email content before sending
POST /v1/tools/content
Heuristic checks on a subject and HTML/text, or on a stored template rendered with sample variables: missing plain text, missing unsubscribe link for marketing email, HTML over 102 KB (Gmail clipping), image-to-text ratio, link count, URL shorteners, links whose text shows another domain, images without alt text, all-caps or !!! subjects, and a short list of phrases spam filters weigh. Not a spam score. Nothing is stored.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
subject | string | |
html | string | |
text | string | |
type | "transactional" | "broadcast" | |
headers | map of string | |
template | string | Template id or slug: checks the rendered template instead of subject/html/text (those override the template when set). |
variables | object | Sample variables for the template. Default: the template test data. |
viaOneSend | boolean | Whether OneSend will send it (it adds List-Unsubscribe headers to broadcasts). Default true. |
Responses
{
"ok": boolean,
"findings": [{
"level": "ok" | "info" | "warning" | "error",
"code": string,
"message": string
}],
"stats": {
"htmlBytes": number,
"textChars": number,
"words": number,
"links": number,
"uniqueLinkDomains": [string],
"images": number,
"imagesWithoutAlt": number,
"subjectLength": number
},
"rendered": {
"subject": string,
"templateId": string,
"version": number
}
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)