Docs / Marketing and deliverability

Deliverability tools

The dashboard's Deliverability tools page (under Sending) and the /v1/tools API check DNS, headers, addresses and content. Checks run only when you ask. Results are not stored on the server; the dashboard keeps the last DNS check and header analysis in your browser so they are still there when you come back.

Every endpoint accepts any API key permission (Full access, Sending only, Read only, test keys) or a dashboard session. They are rate-limited per workspace: DNS-based checks (DNS check, SPF builder, address check) allow a burst of 30 and then 30 per minute; the others a burst of 120 and then 2 per second. Over the limit the API returns 429 rate_limited with Retry-After.

Each result is a list of findings: { "level": "ok" | "info" | "warning" | "error", "code": "…", "message": "…" }. error means the record or message fails or is very likely to hurt delivery, warning that it may, info that it is worth knowing. Codes are stable; messages may change.

ToolEndpointDashboard
DNS checkPOST /v1/tools/dnsDeliverability tools → DNS check
DMARC generatorPOST /v1/tools/dmarcDMARC generator
SPF builderPOST /v1/tools/spfSPF builder
Header analyzerPOST /v1/tools/headersHeader analyzer
Address checkPOST /v1/tools/addressAddress check
Content checkPOST /v1/tools/contentContent check, campaign Review step

The TypeScript SDK has onesend.tools.*, the Python SDK onesend.tools.*, and the MCP server the check_dns, check_content and analyze_headers tools.

DNS check

Checks any domain, not only domains in your workspace.

curl -X POST http://localhost:3000/v1/tools/dns \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain":"example.com","selectors":["s1"]}'
FieldNotes
domainRequired. A URL or an email address is reduced to its domain.
selectorsDKIM selectors (the s= tag of a DKIM-Signature header; the header analyzer shows it). DKIM keys cannot be listed, so without selectors only common names are tried.
checksRun only some of mx, spf, dkim, dmarc, bimi, mta_sts, tls_rpt. Default: all.

What each section checks:

  • MX: records sorted by priority, whether each host has an A or AAAA record, a null MX (0 ., the domain does not receive mail), or no MX at all.
  • SPF: one v=spf1 record (more than one is an error), syntax, and the DNS lookup count through every nested include and redirect. include, a, mx, ptr, exists and redirect each cost a lookup; more than 10 is a permanent error (RFC 7208 §4.6.4), as are more than 2 lookups that find nothing. +all, ?all, a missing all, ptr, include loops and includes without an SPF record are reported. details.tree shows the lookups per include.
  • DKIM: for each selector, the key type and length (RSA keys under 1024 bits are an error, 1024 a warning, 2048 or more passes; Ed25519 is 256 bits), revoked keys (p= empty) and testing mode (t=y).
  • DMARC: the record at _dmarc.<domain>, or the organizational domain's record for a subdomain. Policy (p=none is a warning: it only monitors), sp, pct, rua/ruf, alignment (adkim, aspf), syntax, and whether a report address at another domain is authorized by a <domain>._report._dmarc.<other domain> TXT record (RFC 7489 §7.1). The organizational domain is approximated from the last two labels (three for suffixes such as co.uk); the full Public Suffix List is not used.
  • BIMI (optional): the record at default._bimi.<domain>; the logo URL must use https, is downloaded (at most 512 KB) and checked for SVG with baseProfile="tiny-ps" and a size under 32 KB; a certificate URL (a=) is downloaded and checked for PEM. BIMI also needs DMARC at quarantine or reject with pct=100.
  • MTA-STS (optional): the _mta-sts record with an id, and the policy file at https://mta-sts.<domain>/.well-known/mta-sts.txt (mode and mx lines).
  • TLS-RPT (optional): the _smtp._tls record and its rua.

The overall status is the worst level of MX, SPF, DKIM and DMARC. Problems in the optional records count at most as warnings.

Lookups use DNS-over-HTTPS (Cloudflare's resolver), the same as domain verification. In development, ONESEND_DNS_OVERRIDES answers for the domains it lists (see Testing domains locally). With "*", every lookup under that domain answers with no records. Logos, certificates and policy files are fetched with the same protection as webhooks: only public addresses, a short timeout and a size cap.

DMARC generator

Builds a record from a policy and options and explains each tag. Nothing is published.

POST /v1/tools/dmarc
{ "domain": "example.com", "policy": "quarantine", "pct": 50, "rua": ["dmarc@example.com"] }
→ { "name": "_dmarc.example.com", "record": "v=DMARC1; p=quarantine; pct=50; rua=mailto:dmarc@example.com", "explanation": ["…"] }

Fields: policy (required: none, quarantine, reject), domain, subdomainPolicy, pct (0–100), rua, ruf (up to 5 addresses each, mailto: is added), adkim and aspf (r or s), fo, ri (seconds). Start with p=none and a report address, then move to quarantine and reject once the reports show that all of your own mail passes.

SPF builder

Builds a record from the sending providers connected to your workspace (or the providers you list), extra includes and IP addresses, and counts the DNS lookups it needs by resolving each include.

POST /v1/tools/spf
{ "includes": ["_spf.example.net"], "ip4": ["192.0.2.10"], "all": "~all", "domain": "example.com" }
→ { "record": "v=spf1 ip4:192.0.2.10 include:spf.brevo.com include:_spf.example.net ~all", "lookups": 2, "providers": [ … ], "findings": [ … ], "current": { "domain": "example.com", "record": "…", "lookups": 3 } }

Several providers (Resend, Postmark, SendGrid with automated security, Mailgun, SparkPost) publish SPF on their own return-path subdomain, so their include is not needed on your root domain: DMARC passes through DKIM alignment, and every include costs lookups. They are listed with added: false unless you pass includeSubdomainProviders: true. With domain, the record the domain publishes now is returned in current for comparison. countLookups: false skips DNS.

Header analyzer

Paste the headers of a received message (in most mailboxes: open the message and choose "Show original" or "View source"). The analyzer is pure parsing: no DNS lookups or network.

  • Delivery path: Received headers in the order the message travelled, with the server names, connecting IP, protocol, TLS, and the delay at each hop. Delays over 5 minutes are flagged (greylisting, retry queues or slow filters); a hop dated before the previous one points at a wrong clock.
  • Sending IP: the first public IP in the chain. Private and reserved ranges (including documentation ranges) are skipped.
  • Authentication: SPF, DKIM and DMARC results from the receiving server's Authentication-Results (the topmost one), Received-SPF as a fallback, ARC-Authentication-Results, and the DKIM-Signature domains and selectors.
  • Alignment: whether the SPF domain (smtp.mailfrom) and the passing DKIM domains align with the From domain (relaxed: same organizational domain).
  • Spam filter headers: X-Spam-*, X-*-Antispam*, SCL and similar headers. X-Spam-Flag: YES, X-Spam-Status: Yes and an SCL of 5 or more are reported as problems.
  • One-click unsubscribe headers and a missing Message-ID.

Up to 256 KB of headers. Anything after the first blank line (the body) is ignored.

Address check

For one address (email) or up to 50 (emails):

CheckNotes
Syntaxname@domain.tld, no leading, trailing or double dots before @, at most 64 characters before @.
Mail serversThe domain's MX records; without MX, the A record (the implicit MX, flagged as a warning); a null MX or no records means it cannot receive email.
DisposableA small bundled list of temporary-address domains. It is not complete: treat it as a signal.
Role addressinfo@, admin@, support@, postmaster@ and similar. Role addresses complain and unsubscribe more; avoid them in marketing lists.
SuppressedWhether the address is on this workspace's suppression list, with the reason.

status is valid, risky (role or disposable, or a warning), invalid (syntax, or the domain cannot receive email), suppressed or unknown (DNS could not be reached). The check never connects to the recipient's mail server, so it cannot tell whether a mailbox exists.

Content check

Heuristics on what you are about to send. It is not a spam score from any filter. Send subject, html, text and type (transactional or broadcast), or template (id or slug) with sample variables: the template is rendered on the server (subject and body), with its test data when variables is omitted.

CodeLevelWhat it means
subject_missing, content_missingerrorNo subject or no body.
subject_caps, subject_punctuationwarningMostly capital letters, or !!!, ???, $$.
subject_fake_replywarningRe: or Fwd: on marketing email.
text_missingwarningHTML without a plain-text part. Templates always render one.
html_clippedwarningHTML over 102 KB: Gmail clips it and hides the rest, including the unsubscribe link and open pixel.
image_heavy, image_ratioerror, warning or infoMostly images and little text. 1×1 tracking pixels do not count.
img_alt_missing, img_data_uriwarningImages without alt, or embedded as data: URIs.
links_many, url_shortener, link_ip, link_text_mismatch, link_httpwarning or infoMore than 25 links, shortener domains, IP-address links, link text that shows one domain and points to another, http:// links.
html_script, html_unsupported, html_external_csserror, warning or info<script>, forms, iframes, video, external stylesheets.
spammy_phrasesinfo, or warning from 3A short neutral list of phrases filters weigh, such as "act now" or "risk-free".
unsubscribe_missingerrorMarketing email (broadcast) without a visible unsubscribe link. Add {{ unsubscribe_url }}.
list_unsubscribe, list_unsubscribe_missingok or errorOneSend adds List-Unsubscribe and one-click List-Unsubscribe-Post to campaigns and broadcast sends. With viaOneSend: false the check looks for them in headers.
looks_like_marketinginfoTransactional email with an unsubscribe link: send it as broadcast.

In the dashboard, the campaign Review step has a content check card, and the check is available as a component for the template designer (apps/web/src/pages/tools/ContentCheckPanel.tsx).