domains.create
Register or verify a domain.
Adds a domain to an account and checks DNS verification records (TXT, MX, SPF, DKIM) to activate sending and receiving.
openemail.domains.create(
body: DomainsCreateBody,
options?: CallOptions,
): ApiPromise<DomainsCreateResult>It calls POST /domains: Register or verify a domain in the API reference.
Example
const result = await openemail.domains.create({ domain: 'example.com' })Arguments
| Argument | Type | Description |
|---|---|---|
body | DomainsCreateBody | The request's body. |
Options
It takes no options of its own. Every call also takes signal, timeout, retry and headers, which say how that one call is sent (call options).
Answer
Awaited, it is the API's JSON, DomainsCreateResult. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.
Errors
| Status | What it means |
|---|---|
400 | validation_failed - the body is strict, so an UNRECOGNIZED field (a retired spelling such as the pre-0062 canSend/canReceive) is refused rather than ignored; invalid_domain - the name or aliasOf fails D3 canonicalization (not a convertible, LDH-valid domain; a non-xn label with hyphens at UTS 46 positions 3-4) or D5 (a label whose Unicode form mixes Latin with Cyrillic or Greek); domain_not_verified - the response's record field is the exact ownership TXT to publish, so publish it and POST again; account_required or unknown_account (system caller naming the owner); send_receive_exclusive (sendOnly and receiveOnly together describe a domain the platform does nothing for); or an invalid aliasOf: alias_self, unknown_domain, alias_cross_account, alias_chain, alias_fbl_exclusive |
401 | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge |
403 | ingestion_not_writable: fbl, dmarc and srs turn the whole domain into a report-ingestion sink and are operator state; only a system caller may turn one on. Re-sending the value the domain already carries (as well as false, or omitting them) is unaffected; domain_blocked — the domain, or a parent of it, is on the platform blocklist (migration 0070): refused on the create path only and after proof of control, so an already-registered domain keeps advancing and an unproven caller still sees domain_not_verified |
409 | domain_claimed_elsewhere (the caller proved control, but another account holds the domain — an operator must transfer it), domain_unavailable (identical for every other conflict — no tenant enumeration), account_deleted, alias_conflict, or domain_transition_in_progress (retry after the registration settles) |
413 | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
502 | upstream_unavailable — domain lifecycle transition unavailable |
503 | verification_unavailable — DNS could not be queried, so control could not be proven either way. Retryable; nothing was created. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description) |
A failed call rejects with a RequestError: its status, and its code, the API's error. Decide on the code: one status covers several.
Types
DomainsCreateBody
/** The body of `domains.create`. */
type DomainsCreateBody = {
/** Owning account ULID (required for system callers; ignored for account callers) */
accountId?: string | null
/** Primary domain to alias (all mail rewrites to target domain) */
aliasOf?: string
/** Enable CalDAV/CardDAV autodiscovery DNS checks */
dav?: boolean
/** Aggregate DMARC report-ingestion domain (system callers only) */
dmarc?: boolean
/** Domain name (e.g. 'example.com') */
domain: string
/** Whether the domain is active (default true) */
enabled?: boolean
/** Report-ingestion domain for feedback loops (system callers only) */
fbl?: boolean
/** File arriving calendar invitations, cancellations and replies into the recipient's calendar, and let CalDAV clients schedule through the server (default true). False leaves arriving invitations as ordinary mail */
itip?: boolean
/** Enable JMAP autodiscovery DNS checks */
jmap?: boolean
/** The RECEIVE-ONLY mode (default false), the mirror of `sendOnly`: the domain receives here and its outbound mail goes through somebody else, so `/dns/check` omits the bounce CNAME and both DKIM records — from the checklist AND the verdict — and sending can never be activated. Mutually exclusive with `sendOnly`. */
receiveOnly?: boolean
/** The SEND-ONLY mode (default false): the tenant sends as the domain while its inbound MX stays at another provider — every locality decision treats the domain as external (mail from the platform to it relays to its own MX, group members there are remote forwards, `/dns/check` omits the MX record), and mail arriving at our MX for it is refused `receiving_disabled`. */
sendOnly?: boolean
/** Mark the send records as already proven (system callers only — ignored otherwise: sending is EARNED by this call's own DNS check, so an account body asking for it still converges) */
sendVerified?: boolean
/** SRS bounce-return namespace domain — SRS0=/SRS1= local parts relay DSNs back through the forwarding cluster (system callers only) */
srs?: boolean
/** Whether `+` is a tag delimiter on this domain (default true): mail to `alice+anything@` reaches `alice@` and `alice+*@` is a permitted sender family. False makes `+` an ordinary character — no stripping, no tag recorded, no `+*` family advertised. Read from the canonical domain: inert on an alias */
subaddressing?: boolean
}DomainsCreateResult
/** What `domains.create` answers. */
type DomainsCreateResult = Domain & {
records: DnsRecordCheck[]
}It names these types of the API, each on a page of its own: DnsRecordCheck, Domain.