Connect email domain
Reserves a normalized DNS domain and starts its durable email-provider setup. The accepted provision consumes one email-domain entitlement slot until it fails, is cancelled, or becomes a live resource; the plan’s email.max_email_domains value sets the project limit. The customer resource does not exist until provider identity and DNS setup reach READY; poll the returned operation for progress. A domain may have only one unfinished provision or live resource globally. Email domains have no additional per-domain charge. The Idempotency-Key is required and permanent: replaying the same key and canonical domain returns the original operation forever. Requires the platforms:write permission bound to the project resource in the path. If the operation fails, its error is the problem of one of these codes: EMAIL_DOMAIN_PROVIDER_REJECTED, EMAIL_DOMAIN_VERIFICATION_FAILED, EMAIL_DOMAIN_VERIFICATION_TIMED_OUT, EMAIL_TENANT_SETUP_TIMED_OUT.
Authorizations
Account Service Key, prefixed with pho_ask_, sent as Authorization: Bearer <key>. Acts on behalf of its owning account, subject to the permissions and credential restrictions of each operation. Account access tokens and OAuth grants also use the Bearer header. In organizations that require SSO, Account Service Keys are not accepted for managing the organization's SSO settings, deleting the organization, or checking whether it can be deleted.
Headers
Response
The domain was reserved and setup was dispatched. GET the Location after the Retry-After interval until the operation is terminal.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$"2026-01-01T00:00:00.000Z"
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$"2026-01-01T00:00:00.000Z"
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$"2026-01-01T00:00:00.000Z"
Why the operation failed: the problem of its code, the same object the endpoint returns when it rejects a request, with the status that rejection would have had (the poll itself answers 200). Every code an operation can end with is a branch below, and the endpoint that starts the operation lists its codes. Branch on code, never on status, and keep a default: a code added after your client was generated arrives as a generic problem with type: about:blank and status: 500. That 500 means this document does not describe the code yet, not that the request failed on our side or that retrying will help.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
- Option 14
- Option 15
- Option 16
- Option 17
- Option 18
- Option 19
- Option 20
- Option 21
- Option 22
- Option 23
- Option 24
- Option 25
- Option 26
- Option 27
- Option 28
- Option 29
- Option 30
- Option 31
- Option 32
- Option 33
- Option 34
- Option 35
- Option 36
- Option 37
- Option 38
- Option 39
- Option 40
- Option 41
- Option 42
- Option 43
- Option 44
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$"2026-01-01T00:00:00.000Z"