# 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](/content/docs/cli/commands#global-flags/index.html).

## domains connect

Get Domain Connect setup.

Discovers whether the domain's DNS provider supports Domain Connect (TXT \_domainconnect.\<zone> and the provider's /v2/\<zone>/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 <domain-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<domain-id>` | `string` | required | ID of the domain. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--pod <pod-id>` | `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`](/content/docs/reference/api/domains#get-domain-connect-setup/index.html)
- [`GET /v0/pods/{pod_id}/domains/{domain_id}/domain-connect`](/content/docs/reference/api/domains#get-domain-connect-setup-in-pod/index.html) 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).

allow\_conflicting\_provider, 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 <pod-id>` | `string` |  | Create it in this pod. |
| `--domain <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 <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 <n>` | `integer | null` |  | Make inboxes created by catch-all ephemeral with this TTL. null or absent: permanent. |
| `-d, --data <json|@file|->` | `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`](/content/docs/reference/api/domains#create-domain/index.html)
- [`POST /v0/pods/{pod_id}/domains`](/content/docs/reference/api/domains#create-domain-in-pod/index.html) 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 <domain-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<domain-id>` | `string` | required | ID of the domain. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--pod <pod-id>` | `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}`](/content/docs/reference/api/domains#delete-domain/index.html)
- [`DELETE /v0/pods/{pod_id}/domains/{domain_id}`](/content/docs/reference/api/domains#delete-domain-in-pod/index.html) with `--pod`

## domains get

Get domain.

Requires the domain\_read permission.

```bash
machinemail domains get <domain-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<domain-id>` | `string` | required | ID of the domain. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--pod <pod-id>` | `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}`](/content/docs/reference/api/domains#get-domain/index.html)
- [`GET /v0/pods/{pod_id}/domains/{domain_id}`](/content/docs/reference/api/domains#get-domain-in-pod/index.html) 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 <pod-id>` | `string` |  | Only this pod. |
| `--limit <n>` | `integer` |  | Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`. |
| `--page-token <value>` | `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`](/content/docs/reference/api/domains#list-domains/index.html)
- [`GET /v0/pods/{pod_id}/domains`](/content/docs/reference/api/domains#list-domains-in-pod/index.html) 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 <domain-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<domain-id>` | `string` | required | ID of the domain. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--pod <pod-id>` | `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 <n>` | `integer | null` |  | TTL of inboxes created by catch-all from now on. null makes them permanent. null clears the value. |
| `-d, --data <json|@file|->` | `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}`](/content/docs/reference/api/domains#update-domain/index.html)
- [`PATCH /v0/pods/{pod_id}/domains/{domain_id}`](/content/docs/reference/api/domains#update-domain-in-pod/index.html) with `--pod`

## domains verify

Verify domain.

Checks every DNS record now, updates records[].status and status, 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 <domain-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<domain-id>` | `string` | required | ID of the domain. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--pod <pod-id>` | `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`](/content/docs/reference/api/domains#verify-domain/index.html)
- [`POST /v0/pods/{pod_id}/domains/{domain_id}/verify`](/content/docs/reference/api/domains#verify-domain-in-pod/index.html) with `--pod`

## domains zone-file

Get zone file.

Requires the domain\_read permission.

```bash
machinemail domains zone-file <domain-id> [flags]
```

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<domain-id>` | `string` | required | ID of the domain. |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--pod <pod-id>` | `string` |  | Only this pod. |
| `-o, --output <file|dir|->` | `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`](/content/docs/reference/api/domains#get-zone-file/index.html)
- [`GET /v0/pods/{pod_id}/domains/{domain_id}/zone-file`](/content/docs/reference/api/domains#get-zone-file-in-pod/index.html) with `--pod`