trusted-domains · MachineMail Docs

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.

shell

machinemail trusted-domains create [flags]

Flags

--inbox <inbox-id>string

Create it in this inbox.

--pod <pod-id>string

Create it in this pod.

--domain <domain>string

A domain (example.com) or an exact address (invoices@example.com). Unicode names are accepted and stored in ASCII (punycode) form.

--include-subdomainsboolean

Also trust mail signed by subdomains. Default false. Not allowed for an address.

Defaultfalse

--reason <value>string

Why you trust it, for people reading the list. Never included in a message’s trust report.

--expires-at <time>string

When the entry stops applying. Must be in the future. Omit for never.

--confirmboolean

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

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

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

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

Examples

shell

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-domains
POST /v0/inboxes/{inbox_id}/trusted-domains with --inbox
POST /v0/pods/{pod_id}/trusted-domains with --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.

shell

machinemail trusted-domains delete <trusted-domain-id> [flags]

Arguments

<trusted-domain-id>stringRequired

ID of the entry (td_...).

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

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 --inbox
DELETE /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.

shell

machinemail trusted-domains get <trusted-domain-id> [flags]

Arguments

<trusted-domain-id>stringRequired

ID of the entry (td_...).

Flags

--inbox <inbox-id>string

Only this inbox.

--pod <pod-id>string

Only this pod.

Examples

shell

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 --inbox
GET /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.

shell

machinemail trusted-domains list [flags]

Flags

--inbox <inbox-id>string

Only this inbox.

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

Oldest first.

--allboolean

Follow next_page_token and return every page.

Examples

shell

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-domains
GET /v0/inboxes/{inbox_id}/trusted-domains with --inbox
GET /v0/pods/{pod_id}/trusted-domains with --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.

shell

machinemail trusted-domains preview [flags]

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

--domain <domain>string

A domain (example.com) or an exact address (invoices@example.com). Unicode names are accepted and stored in ASCII (punycode) form.

--include-subdomainsboolean

As for create.

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

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

Examples

shell

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/preview
POST /v0/inboxes/{inbox_id}/trusted-domains/preview with --inbox
POST /v0/pods/{pod_id}/trusted-domains/preview with --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.

shell

machinemail trusted-domains update <trusted-domain-id> [flags]

Arguments

<trusted-domain-id>stringRequired

ID of the entry (td_...).

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

--include-subdomainsboolean

Also trust mail signed by subdomains. Not allowed for an address.

--confirmboolean

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

New reason; null clears it. null clears the value.

--expires-at <time>string | null

New expiry, in the future; null removes it. 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 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

API

PATCH /v0/trusted-domains/{trusted_domain_id}
PATCH /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id} with --inbox
PATCH /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id} with --pod