Register a custom domain
Creates a pending_dns Domain for the caller. Returns the verification TXT host + token and the MX target to publish. Custom domains are a Scale and Business feature (3 and 10 domains by default): a plan that cannot have custom domains at all (Free/Pro; custom_domains cap 0) gets 403 domain_entitlement_required, checked BEFORE the request body is validated. A Scale or Business account that has used its own cap gets 403 domain_limit_reached. 409 domain_taken when the name is already registered by any account, in any status.
Request
- Base URL: https://dash.mailsocket.app/api/v1
- URL: https://dash.mailsocket.app/api/v1/domains
- Auth: HTTP bearer
Headers
Optional. 1-255 printable ASCII characters (use a UUID). Scoped to the API key that sends it and kept for 24 hours. A retry with the same key and the same body replays the first response (with Idempotent-Replayed: true) and creates nothing new. The same key with a different body or endpoint returns 422 idempotency_key_reused; while the first request is still running, 409 idempotency_in_progress. Stored: 2xx, and 400/404/422 validation errors. Not stored (a retry runs again): outcomes you can fix and retry (402, 403, 409, and 422 domain_not_found_or_unverified), 429 and 5xx. An invalid value, or a body too large to read, returns 400 validation_error.
Request body
Response
Domain created.
Changes
No recorded changes to this operation across all 1 revision of this API.