---
title: "Tools API"
description: "Tools in the OneSend API: 6 endpoints. Deliverability tools: DNS checker for any domain, DMARC and SPF builders, header analyzer, address checker and pre-send content check. Results are not stored."
url: https://onesend.email/docs/api-reference/tools/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# 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.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `domain`required | `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

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `domain` | `string` | Domain name, for example example.com. A URL or an email address is reduced to its domain. |
| `policy`required | `"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

`200` Success

```
{
  "name": string or null,
  "record": string,
  "explanation": [string]
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

application/json, required.

| 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

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `headers`required | `string` | Raw message headers as copied from "Show original" or "View source". |

### Responses

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email` | `string` |  |
| `emails` | `array of string` | At most 50 items. |

### Responses

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected 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

application/json, required.

| 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

`200` Success

```
{
  "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**

- `400` Invalid 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`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), 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 missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
