trusted-domains · MachineMail Docs
trusted-domains create
Domains and addresses the organization, a pod or an inbox trusts: mail they genuinely sign is never quarantined or withheld from agents. Trust never beats a block entry or opens an allow-only scope.
| Command | Summary |
|---|---|
trusted-domains create |
Create trusted domain |
trusted-domains delete |
Delete trusted domain |
trusted-domains get |
Get trusted domain |
trusted-domains list |
List trusted domains |
trusted-domains preview |
Preview trusted domain |
trusted-domains update |
Update trusted domain |
Every command also takes the global flags.
trusted-domains create
Create trusted domain.
Trust a domain (example.com) or one address ( invoices@example.com) at this level. Domains are stored in ASCII (punycode) form; responses carry both forms. Adding an entry that exists at this level (the same domain, or the same —client-id) returns it unchanged with 200.
Trust takes effect only on mail that carries a DKIM signature of the trusted domain itself (d= equal to the domain, or a subdomain with —include-subdomains); a block entry always wins over trust, and an allow-only scope still blocks every sender it does not allow.
Conflicts with block entries and allow-only scopes do not refuse the entry: they are returned as warnings.
Refused with 422: trusted_domain_not_allowed for names anyone can get mail from (error.reason: free_mail, privacy_relay, shared_platform, public_suffix, disposable, invalid, confusable_idn); confirmation_required for platforms where anyone can write the content (github.com, google.com, slack.com and similar, or one under the domain with —include-subdomains) and for one address on a group or marketplace relay ( team@googlegroups.com), until you resend with —confirm. An address on a free mail provider ( someone@gmail.com) can be trusted.
Refused with 402 plan_limit_exceeded (limit_key: “trusted_domains”) past the organization’s limit: 10 on Free, 500 on paid plans, none for unclaimed sandbox agents. Entries at every level count.
Only an organization API key or a dashboard session can add or change an entry: pod and inbox keys, OAuth apps and agent access tokens get 403, whatever their permissions, so an agent cannot be talked into trusting a domain.
Requires the trusted_domain_create permission.
machinemail trusted-domains create [flags]
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Create it in this inbox. |
--pod <pod-id> |
Create it in this pod. |
--domain <domain> |
A domain (example.com) or an exact address (invoices@example.com). Unicode names are accepted and stored in ASCII (punycode) form. |
--include-subdomains |
Also trust mail signed by subdomains. Default false. Not allowed for an address. |
--reason <value> |
Why you trust it, for people reading the list. Never included in a message’s trust report. |
--expires-at <time> |
When the entry stops applying. Must be in the future. Omit for never. |
--confirm |
Required (true) for platforms where anyone can write the content (github.com, google.com, slack.com and similar, or one under the domain with --include-subdomains) and for one address on a group or marketplace relay (team@googlegroups.com): without it the answer is 422 confirmation_required. |
--client-id <id> |
Idempotency key: a create with a --client-id already used in the organization returns that entry (200). |
| `-d, --data <json | @file |
Examples
machinemail trusted-domains create --domain mail.example.com
machinemail trusted-domains create --domain mail.example.com --inbox agent@machinemail.dev
machinemail trusted-domains create --data @body.json
API
POST /v0/trusted-domainsPOST /v0/inboxes/{inbox_id}/trusted-domainswith--inboxPOST /v0/pods/{pod_id}/trusted-domainswith--pod
trusted-domains delete
Delete trusted domain.
Also: machinemail trusted-domains rm.
Mail from the domain is judged normally again from now on. Any credential with trusted_domain_delete that can see the entry may remove it.
Requires the trusted_domain_delete permission.
machinemail trusted-domains delete <trusted-domain-id> [flags]
Arguments
| Field | Description |
|---|---|
<trusted-domain-id> |
ID of the entry (td_...). |
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Use this inbox's scoped route. |
--pod <pod-id> |
Use this pod's scoped route. |
Examples
machinemail trusted-domains delete <trusted-domain-id>
machinemail trusted-domains delete <trusted-domain-id> --inbox agent@machinemail.dev
API
DELETE /v0/trusted-domains/{trusted_domain_id}DELETE /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id}with--inboxDELETE /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id}with--pod
trusted-domains get
Get trusted domain.
An entry stored at this level (404 for entries at another level).
Requires the trusted_domain_read permission.
machinemail trusted-domains get <trusted-domain-id> [flags]
Arguments
| Field | Description |
|---|---|
<trusted-domain-id> |
ID of the entry (td_...). |
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Only this inbox. |
--pod <pod-id> |
Only this pod. |
Examples
machinemail trusted-domains get <trusted-domain-id>
machinemail trusted-domains get <trusted-domain-id> --inbox agent@machinemail.dev
API
GET /v0/trusted-domains/{trusted_domain_id}GET /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id}with--inboxGET /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id}with--pod
trusted-domains list
List trusted domains.
Also: machinemail trusted-domains ls.
Entries stored at exactly this level: /v0/trusted-domains lists the organization entries, /v0/pods/{pod_id}/trusted-domains a pod’s, /v0/inboxes/{inbox_id}/trusted-domains an inbox’s. Mail to an inbox is judged against all three.
Requires the trusted_domain_read permission.
machinemail trusted-domains list [flags]
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Only this inbox. |
--pod <pod-id> |
Only this pod. |
--limit <n> |
Maximum number of items to return. Default 50, maximum 500; larger values are capped. |
--page-token <value> |
next_page_token from the previous page. |
--ascending |
Oldest first. |
--all |
Follow next_page_token and return every page. |
Examples
machinemail trusted-domains list
machinemail trusted-domains list --inbox agent@machinemail.dev
machinemail trusted-domains list --all --json | jq '.trusted_domains | length'
API
GET /v0/trusted-domainsGET /v0/inboxes/{inbox_id}/trusted-domainswith--inboxGET /v0/pods/{pod_id}/trusted-domainswith--pod
trusted-domains preview
Preview trusted domain.
What creating this entry at this level would do, without saving anything: whether it is allowed (and if not, why), whether it needs confirm: true, and its warnings. For validating as someone types. would_release and suggestions are not computed yet and are always null.
Requires the trusted_domain_read permission.
machinemail trusted-domains preview [flags]
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Use this inbox's scoped route. |
--pod <pod-id> |
Use this pod's scoped route. |
--domain <domain> |
A domain (example.com) or an exact address (invoices@example.com). Unicode names are accepted and stored in ASCII (punycode) form. |
--include-subdomains |
As for create. |
| `-d, --data <json | @file |
Examples
machinemail trusted-domains preview --domain mail.example.com
machinemail trusted-domains preview --domain mail.example.com --inbox agent@machinemail.dev
machinemail trusted-domains preview --data @body.json
API
POST /v0/trusted-domains/previewPOST /v0/inboxes/{inbox_id}/trusted-domains/previewwith--inboxPOST /v0/pods/{pod_id}/trusted-domains/previewwith--pod
trusted-domains update
Update trusted domain.
Change —include-subdomains, —reason or —expires-at. The domain and level are fixed: delete and create to change them. Turning on —include-subdomains is checked like a create with it: refused (422 trusted_domain_not_allowed) when a privacy relay or MachineMail shared domain lies under the domain, and 422 confirmation_required until you send —confirm when a platform where anyone can write the content does. Returns the entry with its current warnings. Only an organization API key or a dashboard session can add or change an entry: pod and inbox keys, OAuth apps and agent access tokens get 403, whatever their permissions, so an agent cannot be talked into trusting a domain.
Requires the trusted_domain_update permission.
machinemail trusted-domains update <trusted-domain-id> [flags]
Arguments
| Field | Description |
|---|---|
<trusted-domain-id> |
ID of the entry (td_...). |
Flags
| Field | Description |
|---|---|
--inbox <inbox-id> |
Use this inbox's scoped route. |
--pod <pod-id> |
Use this pod's scoped route. |
--include-subdomains |
Also trust mail signed by subdomains. Not allowed for an address. |
--confirm |
Required (true) to turn on --include-subdomains when a platform where anyone can write the content lies under the domain: without it the answer is 422 confirmation_required. |
--reason <value> |
New reason; null clears it. null clears the value. |
--expires-at <time> |
New expiry, in the future; null removes it. null clears the value. |
| `-d, --data <json | @file |
Examples
machinemail trusted-domains update <trusted-domain-id>
machinemail trusted-domains update <trusted-domain-id> --inbox agent@machinemail.dev
machinemail trusted-domains update <trusted-domain-id> --data @body.json
machinemail trusted-domains update <trusted-domain-id> --reason null # clears reason