POST/sending/domains

POST /sending/domains

Add a sending domain. Returns the DNS records to publish: the provider DKIM records, an advisory DMARC record, an ownership challenge TXT record and, when the mail subdomain is free, the MAIL FROM MX and SPF records.

View as Markdown

Request

curl -X POST 'https://api.sendheron.com/api/v1/sending/domains' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

sending:write

Body parameters

Name	Type	Required	Description
domain	string	Yes	The domain to authenticate, without scheme or path, e.g. `mail.acme.com`. Case and a trailing dot are normalized away. Authenticating a domain covers every address under it, including subdomains.

Publish the returned records, then call verify. To see them as receivers will, look them up once they are published: the DKIM checker takes the domain and a DKIM record's selector, the part of its name before ._domainkey, and follows the record to the key the way receivers do; the SPF checker reads the SPF record on the mail subdomain, when one was returned; and the DMARC checker reads the DMARC record. The ownership challenge is omitted in exactly one case: when this organization has already verified the same domain in another workspace, the domain is authenticated immediately and needs no DNS at all. A domain that is still not verified 7 days after it was added is removed by a daily cleanup; add it again to start over.

Responses

Returns 201 on success.

400: The payload failed validation, or the request is not valid for the current state. The body's description names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The error code is stable and safe to branch on; description is for the human reading the log.
401: Missing or invalid API key.
403: Valid key, but it does not carry the required scope. The error code is apiKeys.insufficientScopes and the description names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404: No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409: A duplicate, or an idempotency key reused with a different payload.
429: Either rate-limit ceiling was exceeded.
409: This workspace already has this domain.
403: subscription.domainCapReached: the organization has used every sending domain its plan allows. The pricing page lists the number per plan, and a trial allows one sending domain until it converts. Domains are counted once across the whole organization, so adding one you already hold in another workspace never trips it. A larger plan raises the limit; GET /usage reports where you stand in domains.
403: subscription.lapsed: the organization has no live subscription, and adding a domain is refused until it has one again.

Rate limits

100/min per key, counted against the organization's WRITE ceiling (400/min). Both windows are one minute.