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 and errors are described in the overview.

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.

FieldTypeDescription
domainrequiredstringDomain name, for example example.com. A URL or an email address is reduced to its domain.
selectorsarray of stringDKIM selectors to check (the s= tag of a DKIM-Signature). Without them, common selector names are tried. At most 20 items.
checksarray 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.

FieldTypeDescription
domainstringDomain 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
pctinteger0 to 100.
ruaarray of stringAddresses for aggregate reports. At most 5 items.
rufarray of stringAddresses for failure reports. At most 5 items.
adkim"r" | "s"
aspf"r" | "s"
fostring
riinteger3600 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.

FieldTypeDescription
domainstringCompare with the SPF record published for this domain.
providersarray of stringProvider ids. Default: the sending providers connected to this workspace. At most 30 items.
includesarray of stringAt most 20 items.
ip4array of stringAt most 20 items.
ip6array of stringAt most 20 items.
mxboolean
aboolean
all"-all" | "~all" | "?all"
includeSubdomainProvidersbooleanAlso add includes for providers that publish SPF on their own return-path subdomain.
countLookupsbooleanResolve 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.

FieldTypeDescription
headersrequiredstringRaw 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.

FieldTypeDescription
emailstring
emailsarray of stringAt 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.

FieldTypeDescription
subjectstring
htmlstring
textstring
type"transactional" | "broadcast"
headersmap of string
templatestringTemplate id or slug: checks the rendered template instead of subject/html/text (those override the template when set).
variablesobjectSample variables for the template. Default: the template test data.
viaOneSendbooleanWhether 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)