Domains

Add a custom send domain

Requires scope: manage. Registers a bring-your-own sending domain (paid plans). Returns the DNS records to create at your registrar — records-only verification, no nameserver changes. Agents whose address is on a VERIFIED custom domain send under their own identity instead of the shared workspace subdomain. A domain that is already added, to this workspace or to another, is refused with 400 duplicate_resource.

post/v1/domains

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/domains
  • Auth: HTTP bearer

Request body

domainstring required

The domain to send from, such as mail.acme.com, 4 to 253 characters, lowercased and without a trailing dot. A name that is not a valid hostname, is under mails.ai, or is already added to any workspace is refused with 400.

Response

The registered domain with the DNS records to create.

idstring required

Domain id (dom_…).

domainstring required

The custom sending domain, lowercased.

status'pending' | 'verifying' | 'verified' | 'failed' required

pending → records issued; verifying → checks in progress; verified → agents on this domain send under their own identity; failed → 20 verify calls in a row did not pass. Not final: a failed domain is still re-checked automatically (less often the longer it fails, at most a day apart) and verifies by itself once its records resolve; verify still checks at once, and the count starts over on success or after a day without a verify call.

providerstring

Backing sending infrastructure for this domain.

fail_reasonstring nullable

Why the last verification did not pass, when it didn't.

last_check_atstring date-time nullable

When the records were last checked: by a verify call, by the automatic re-checks of unverified domains, or by the daily re-check of verified ones. Null before the first check.

verified_atstring date-time nullable

When the domain first verified. Null until then, and cleared again when the daily re-check of verified domains (06:40 UTC) finds a required record gone.

created_atstring date-time required

When the domain was added (UTC).

Changes

No recorded changes to this operation across all 1 revision of this API.