Skip to navigation

Add a custom domain

View as Markdown

Adds a new custom domain to your account and returns the DNS records you must configure at your registrar before verifying.

Plan required: Growth (49/mo)orEnterprise(49/mo) or Enterprise (149/mo).

Workflow:

  1. POST /v1/custom-domains — add the domain, get DNS records.
  2. Add the two DNS records (MX + TXT) at your registrar.
  3. POST /v1/custom-domains/{domain}/verify — confirm propagation.
  4. POST /v1/inboxes with any address @yourdomain — start receiving mail.

This call is idempotent — if the domain is already added it returns the existing entry with 200 instead of 201.

Limits: Maximum 10 custom domains per account.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
domainstringRequired

Response

OK
successboolean
messagestring
dataobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error