domains · MachineMail Docs

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.

shell

machinemail domains connect <domain-id> [flags]

Arguments

<domain-id>stringRequired

ID of the domain.

Flags

--pod <pod-id>string

Only this pod.

Examples

shell

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 and INVALID domains about every 5 minutes until 7 days after creation; a NOT_STARTED domain is only checked by Verify Domain.

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.

Requires the domain_create permission.

shell

machinemail domains create [flags]

Flags

--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-enabledboolean

Stored and returned; has no effect. Default false.

Defaultfalse

--inbound-enabledboolean

Receive email for this domain. Default true. false makes it send-only (the inbound MX record is not required).

Defaulttrue

--client-id <id>string

Idempotency key: a create with a --client-id already used in the organization returns that domain with 200.

--catch-allboolean

Create an inbox for any address at the domain that receives mail. Default false.

Defaultfalse

--catch-all-ttl-seconds <n>integer | null

Make inboxes created by catch-all ephemeral with this TTL. null or absent: permanent. null clears the value.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

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.

shell

machinemail domains delete <domain-id> [flags]

Arguments

<domain-id>stringRequired

ID of the domain.

Flags

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

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.

shell

machinemail domains get <domain-id> [flags]

Arguments

<domain-id>stringRequired

ID of the domain.

Flags

--pod <pod-id>string

Only this pod.

Examples

shell

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.

shell

machinemail domains list [flags]

Flags

--pod <pod-id>string

Only this pod.

--limit <n>integer

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

Default50

--page-token <value>string

next_page_token from the previous page.

--ascendingboolean

Sort oldest first.

--allboolean

Follow next_page_token and return every page.

Examples

shell

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.

shell

machinemail domains update <domain-id> [flags]

Arguments

<domain-id>stringRequired

ID of the domain.

Flags

--pod <pod-id>string

Use this pod's scoped route.

--feedback-enabledboolean

Stored and returned; has no effect.

--inbound-enabledboolean

Receive email for this domain. false makes the inbound MX record optional and re-evaluates the status.

--catch-allboolean

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

shell

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.

shell

machinemail domains verify <domain-id> [flags]

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.

shell

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

Arguments

<domain-id>stringRequired

ID of the domain.

Flags

--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

shell

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