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.
| Tool | Endpoint | Dashboard |
|---|---|---|
| DNS check | POST /v1/tools/dns | Deliverability tools → DNS check |
| DMARC generator | POST /v1/tools/dmarc | DMARC generator |
| SPF builder | POST /v1/tools/spf | SPF builder |
| Header analyzer | POST /v1/tools/headers | Header analyzer |
| Address check | POST /v1/tools/address | Address check |
| Content check | POST /v1/tools/content | Content 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"]}'
| Field | Notes |
|---|---|
domain | Required. A URL or an email address is reduced to its domain. |
selectors | DKIM 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. |
checks | Run 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=spf1record (more than one is an error), syntax, and the DNS lookup count through every nestedincludeandredirect.include,a,mx,ptr,existsandredirecteach 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 missingall,ptr, include loops and includes without an SPF record are reported.details.treeshows 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=noneis 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 asco.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 withbaseProfile="tiny-ps"and a size under 32 KB; a certificate URL (a=) is downloaded and checked for PEM. BIMI also needs DMARC atquarantineorrejectwithpct=100. - MTA-STS (optional): the
_mta-stsrecord with anid, and the policy file athttps://mta-sts.<domain>/.well-known/mta-sts.txt(mode andmxlines). - TLS-RPT (optional): the
_smtp._tlsrecord and itsrua.
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:
Receivedheaders 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-SPFas a fallback,ARC-Authentication-Results, and theDKIM-Signaturedomains 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: Yesand 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):
| Check | Notes |
|---|---|
| Syntax | name@domain.tld, no leading, trailing or double dots before @, at most 64 characters before @. |
| Mail servers | The 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. |
| Disposable | A small bundled list of temporary-address domains. It is not complete: treat it as a signal. |
| Role address | info@, admin@, support@, postmaster@ and similar. Role addresses complain and unsubscribe more; avoid them in marketing lists. |
| Suppressed | Whether 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.
| Code | Level | What it means |
|---|---|---|
subject_missing, content_missing | error | No subject or no body. |
subject_caps, subject_punctuation | warning | Mostly capital letters, or !!!, ???, $$. |
subject_fake_reply | warning | Re: or Fwd: on marketing email. |
text_missing | warning | HTML without a plain-text part. Templates always render one. |
html_clipped | warning | HTML over 102 KB: Gmail clips it and hides the rest, including the unsubscribe link and open pixel. |
image_heavy, image_ratio | error, warning or info | Mostly images and little text. 1×1 tracking pixels do not count. |
img_alt_missing, img_data_uri | warning | Images without alt, or embedded as data: URIs. |
links_many, url_shortener, link_ip, link_text_mismatch, link_http | warning or info | More 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_css | error, warning or info | <script>, forms, iframes, video, external stylesheets. |
spammy_phrases | info, or warning from 3 | A short neutral list of phrases filters weigh, such as "act now" or "risk-free". |
unsubscribe_missing | error | Marketing email (broadcast) without a visible unsubscribe link. Add {{ unsubscribe_url }}. |
list_unsubscribe, list_unsubscribe_missing | ok or error | OneSend 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_marketing | info | Transactional 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).