--- title: "domains" description: "Custom domains, DNS records, catch-all. The `machinemail domains` commands: arguments, flags, examples and the API routes they call." canonical: "https://machinemail.dev/docs/cli/commands/domains" --- # domains > Custom domains, DNS records, catch-all. The `machinemail domains` commands: arguments, flags, examples and the API routes they call. Source: https://machinemail.dev/docs/cli/commands/domains Custom domains, DNS records, catch-all. Also spelled `domain`. | Command | Summary | | ----------------------------------------- | ------------------------ | | [`domains connect`](#domains-connect) | Get Domain Connect setup | | [`domains create`](#domains-create) | Create domain | | [`domains delete`](#domains-delete) | Delete domain | | [`domains get`](#domains-get) | Get domain | | [`domains list`](#domains-list) | List domains | | [`domains update`](#domains-update) | Update domain | | [`domains verify`](#domains-verify) | Verify domain | | [`domains zone-file`](#domains-zone-file) | Get zone file | Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags). ## domains connect Get Domain Connect setup. Discovers whether the domain's DNS provider supports Domain Connect (TXT \_domainconnect.\ and the provider's /v2/\/settings) and has onboarded the MachineMail template (machinemail.dev/email). When it has, apply\_url is a signed synchronous-flow link (RS256, key=\_dck1, sig last) that opens the provider with the outstanding MX, SPF, DKIM and DMARC records prefilled. Discovery is cached on the domain (6 h; provider errors 10 min) and re-run by Verify Domain. Requires the domain\_read permission. ```bash machinemail domains connect [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the domain. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Only this pod. | #### Examples ```bash machinemail domains connect dom_01m4fz9w5k0000h3n8c2q7t4ra machinemail domains connect dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx ``` #### API - [`GET /v0/domains/{domain_id}/domain-connect`](https://machinemail.dev/docs/reference/api/domains#get-domain-connect-setup) - [`GET /v0/pods/{pod_id}/domains/{domain_id}/domain-connect`](https://machinemail.dev/docs/reference/api/domains#get-domain-connect-setup-in-pod) with `--pod` ## domains create Create domain. Registers the domain and returns the DNS records to publish (status: NOT\_STARTED). Publish them, then call Verify Domain. A background worker re-checks PENDING, INVALID and VERIFYING domains about every 5 minutes until 7 days after creation; a NOT\_STARTED domain is only checked by Verify Domain. A domain that is never verified is removed 14 days after it was added, together with its inboxes and the mail in them; owners and admins of the organization are emailed at least 3 days before. A domain that was verified once is never removed this way. A domain can be registered by one organization only (409), and the shared domain cannot be added (409). Inbox-scoped credentials cannot add domains (403). The domain's current DNS is looked up as it is added. Existing records that conflict with the ones to publish (MX records of another mail provider, an SPF record at the same name, a CNAME at a name that needs another record) are returned in dns\_conflicts, each with what to do about it. Conflicts never refuse the domain, so allow\_conflicting\_provider is not supported; when the lookup does not complete, the domain is added without dns\_conflicts. subdomains\_enabled and tracking\_enabled are not supported. 502 upstream\_error when the email provider cannot register the domain (for example its domain capacity is reached, or it is rate limiting registrations): nothing is created. Requires the domain\_create permission. ```bash machinemail domains create [flags] ``` #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Create it in this pod. | | `--domain ` | `string` | | The domain name, for example example.com. Cannot be the shared domain or a domain another organization registered. | | `--feedback-enabled` | `boolean` | | Stored and returned; has no effect. Default false. Default: `false`. | | `--inbound-enabled` | `boolean` | | Receive email for this domain. Default true. false makes it send-only (the inbound MX record is not required). Default: `true`. | | `--client-id ` | `string` | | Idempotency key: a create with a --client-id already used in the organization returns that domain with 200, or 409 when that domain is outside the pod of the API key or route. | | `--catch-all` | `boolean` | | Create an inbox for any address at the domain that receives mail. Default false. Default: `false`. | | `--catch-all-ttl-seconds ` | `integer \| null` | | Make inboxes created by catch-all ephemeral with this TTL. null or absent: permanent. | | `-d, --data ` | `string` | | Request body as JSON, @file or - for stdin; field flags override its keys. | #### Examples ```bash machinemail domains create --domain mail.example.com machinemail domains zone-file mail.example.com > zone.txt machinemail domains create --domain mail.example.com --pod pod_01m4fykg210000x6z8b6wc2rdx machinemail domains create --data @body.json ``` #### API - [`POST /v0/domains`](https://machinemail.dev/docs/reference/api/domains#create-domain) - [`POST /v0/pods/{pod_id}/domains`](https://machinemail.dev/docs/reference/api/domains#create-domain-in-pod) with `--pod` ## domains delete Delete domain. Also: `machinemail domains rm`. Inboxes on the domain are not deleted. Requires the domain\_delete permission. ```bash machinemail domains delete [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the domain. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Use this pod's scoped route. | #### Examples ```bash machinemail domains delete dom_01m4fz9w5k0000h3n8c2q7t4ra machinemail domains delete dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx ``` #### API - [`DELETE /v0/domains/{domain_id}`](https://machinemail.dev/docs/reference/api/domains#delete-domain) - [`DELETE /v0/pods/{pod_id}/domains/{domain_id}`](https://machinemail.dev/docs/reference/api/domains#delete-domain-in-pod) with `--pod` ## domains get Get domain. Requires the domain\_read permission. ```bash machinemail domains get [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the domain. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Only this pod. | #### Examples ```bash machinemail domains get dom_01m4fz9w5k0000h3n8c2q7t4ra machinemail domains get dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx ``` #### API - [`GET /v0/domains/{domain_id}`](https://machinemail.dev/docs/reference/api/domains#get-domain) - [`GET /v0/pods/{pod_id}/domains/{domain_id}`](https://machinemail.dev/docs/reference/api/domains#get-domain-in-pod) with `--pod` ## domains list List domains. Also: `machinemail domains ls`. Requires the domain\_read permission. ```bash machinemail domains list [flags] ``` #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Only this pod. | | `--limit ` | `integer` | | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. | | `--page-token ` | `string` | | next_page_token from the previous page. | | `--ascending` | `boolean` | | Sort oldest first. | | `--all` | `boolean` | | Follow next_page_token and return every page. | #### Examples ```bash machinemail domains list machinemail domains list --pod pod_01m4fykg210000x6z8b6wc2rdx machinemail domains list --all --json | jq '.domains | length' ``` #### API - [`GET /v0/domains`](https://machinemail.dev/docs/reference/api/domains#list-domains) - [`GET /v0/pods/{pod_id}/domains`](https://machinemail.dev/docs/reference/api/domains#list-domains-in-pod) with `--pod` ## domains update Update domain. Fields you omit are unchanged. subdomains\_enabled and tracking\_enabled are not supported. Requires the domain\_update permission. ```bash machinemail domains update [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the domain. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Use this pod's scoped route. | | `--feedback-enabled` | `boolean` | | Stored and returned; has no effect. | | `--inbound-enabled` | `boolean` | | Receive email for this domain. false makes the inbound MX record optional and re-evaluates the status. | | `--catch-all` | `boolean` | | Create an inbox for any address at the domain that receives mail. | | `--catch-all-ttl-seconds ` | `integer \| null` | | TTL of inboxes created by catch-all from now on. null makes them permanent. null clears the value. | | `-d, --data ` | `string` | | Request body as JSON, @file or - for stdin; field flags override its keys. | #### Examples ```bash machinemail domains update dom_01m4fz9w5k0000h3n8c2q7t4ra machinemail domains update dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx machinemail domains update dom_01m4fz9w5k0000h3n8c2q7t4ra --data @body.json machinemail domains update dom_01m4fz9w5k0000h3n8c2q7t4ra --catch-all-ttl-seconds null # clears catch-all-ttl-seconds ``` #### API - [`PATCH /v0/domains/{domain_id}`](https://machinemail.dev/docs/reference/api/domains#update-domain) - [`PATCH /v0/pods/{pod_id}/domains/{domain_id}`](https://machinemail.dev/docs/reference/api/domains#update-domain-in-pod) with `--pod` ## domains verify Verify domain. Checks every DNS record now, updates records\[].status, status and dns\_conflicts, and re-runs Domain Connect discovery. A domain.verified event is emitted when the domain becomes VERIFIED. Requires the domain\_update permission. ```bash machinemail domains verify [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the domain. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Use this pod's scoped route. | #### Examples ```bash machinemail domains verify dom_01m4fz9w5k0000h3n8c2q7t4ra machinemail domains verify dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx ``` #### API - [`POST /v0/domains/{domain_id}/verify`](https://machinemail.dev/docs/reference/api/domains#verify-domain) - [`POST /v0/pods/{pod_id}/domains/{domain_id}/verify`](https://machinemail.dev/docs/reference/api/domains#verify-domain-in-pod) with `--pod` ## domains zone-file Get zone file. Requires the domain\_read permission. ```bash machinemail domains zone-file [flags] ``` #### Arguments | Field | Type | | Description | | --- | --- | --- | --- | | `` | `string` | required | ID of the domain. | #### Flags | Field | Type | | Description | | --- | --- | --- | --- | | `--pod ` | `string` | | Only this pod. | | `-o, --output ` | `string` | | Write the body to this file (a directory keeps the server's filename; - is stdout) and report the path. | #### Examples ```bash machinemail domains zone-file dom_01m4fz9w5k0000h3n8c2q7t4ra machinemail domains zone-file dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx ``` #### API - [`GET /v0/domains/{domain_id}/zone-file`](https://machinemail.dev/docs/reference/api/domains#get-zone-file) - [`GET /v0/pods/{pod_id}/domains/{domain_id}/zone-file`](https://machinemail.dev/docs/reference/api/domains#get-zone-file-in-pod) with `--pod`