---
title: "Deliverability tools"
description: "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."
url: https://onesend.email/docs/tools/
---
# 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](#dns-check) | `POST /v1/tools/dns` | Deliverability tools → DNS check |
| [DMARC generator](#dmarc-generator) | `POST /v1/tools/dmarc` | DMARC generator |
| [SPF builder](#spf-builder) | `POST /v1/tools/spf` | SPF builder |
| [Header analyzer](#header-analyzer) | `POST /v1/tools/headers` | Header analyzer |
| [Address check](#address-check) | `POST /v1/tools/address` | Address check |
| [Content 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.

<a id="dns-check"></a>
## DNS check

Checks any domain, not only domains in your workspace.

```bash
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=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](https://onesend.email/docs/domains-and-dns/#testing-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.

<a id="dmarc-generator"></a>
## DMARC generator

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

```json
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.

<a id="spf-builder"></a>
## 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.

```json
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.

<a id="header-analyzer"></a>
## 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.

<a id="address-check"></a>
## 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.

<a id="content-check"></a>
## 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`).
