domains.md

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`	Get Domain Connect setup
`domains create`	Create domain
`domains delete`	Delete domain
`domains get`	Get domain
`domains list`	List domains
`domains update`	Update domain
`domains verify`	Verify domain
`domains zone-file`	Get zone file

Every command also takes the global flags.

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.

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

machinemail domains connect dom_01m4fz9w5k0000h3n8c2q7t4ra
machinemail domains connect dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx

API

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.

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`
`-d, --data <json	@file	->`	`string`

Examples

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
POST /v0/pods/{pod_id}/domains with --pod

domains delete

Delete domain.

Also: machinemail domains rm.

Inboxes on the domain are not deleted.

Requires the domain_delete permission.

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

machinemail domains delete dom_01m4fz9w5k0000h3n8c2q7t4ra
machinemail domains delete dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx

API

DELETE /v0/domains/{domain_id}
DELETE /v0/pods/{pod_id}/domains/{domain_id} with --pod

domains get

Get domain.

Requires the domain_read permission.

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

machinemail domains get dom_01m4fz9w5k0000h3n8c2q7t4ra
machinemail domains get dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx

API

GET /v0/domains/{domain_id}
GET /v0/pods/{pod_id}/domains/{domain_id} with --pod

domains list

List domains.

Also: machinemail domains ls.

Requires the domain_read permission.

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

machinemail domains list
machinemail domains list --pod pod_01m4fykg210000x6z8b6wc2rdx
machinemail domains list --all --json | jq '.domains | length'

API

GET /v0/domains
GET /v0/pods/{pod_id}/domains with --pod

domains update

Update domain.

Fields you omit are unchanged. subdomains_enabled and tracking_enabled are not supported.

Requires the domain_update permission.

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`
`-d, --data <json	@file	->`	`string`

Examples

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}
PATCH /v0/pods/{pod_id}/domains/{domain_id} 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.

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

machinemail domains verify dom_01m4fz9w5k0000h3n8c2q7t4ra
machinemail domains verify dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx

API

domains zone-file

Get zone file.

Requires the domain_read permission.

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`

Examples

machinemail domains zone-file dom_01m4fz9w5k0000h3n8c2q7t4ra
machinemail domains zone-file dom_01m4fz9w5k0000h3n8c2q7t4ra --pod pod_01m4fykg210000x6z8b6wc2rdx