---
title: "trusted-domains"
description: "Manage the domains and addresses whose signed mail is never quarantined, for the organization, a pod or an inbox, from the MachineMail CLI: flags and examples."
canonical: "https://machinemail.dev/docs/cli/commands/trusted-domains"
---

# trusted-domains

> Manage the domains and addresses whose signed mail is never quarantined, for the organization, a pod or an inbox, from the MachineMail CLI: flags and examples.

Source: https://machinemail.dev/docs/cli/commands/trusted-domains

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`](#trusted-domains-create)           | Create trusted domain   |
| [`trusted-domains delete`](#trusted-domains-delete)           | Delete trusted domain   |
| [`trusted-domains get`](#trusted-domains-get)                 | Get trusted domain      |
| [`trusted-domains list`](#trusted-domains-list)               | List trusted domains    |
| [`trusted-domains preview`](#trusted-domains-preview)         | Preview trusted domain  |
| [`trusted-domains suggestions`](#trusted-domains-suggestions) | Suggest trusted domains |
| [`trusted-domains update`](#trusted-domains-update)           | Update trusted domain   |

Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#global-flags).

## trusted-domains create

Create trusted domain.

Trust a domain (example.com) or one address ([invoices@example.com](mailto: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.

With --apply-to-existing, held mail of the last 30 days that the new entry vouches for is released (released.count): mail held for sender or authentication-history reasons that carries the domain’s own DKIM signature, never mail held for malware, instructions to agents or phishing, mail a person quarantined, or mail a block or allow-only scope stops. Each released message emits message.released (not message.received); a large backlog is released in the background after the response. An existing entry (200) releases nothing.

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](mailto:team@googlegroups.com)), until you resend with --confirm. An address on a free mail provider ([someone@gmail.com](mailto: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.

```bash
machinemail trusted-domains create [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Create it in this inbox. |
| `--pod <pod-id>` | `string` |  | Create it in this pod. |
| `--idempotency-key <value>` | `string` |  | Makes the request safe to retry: a retry with the same key within 24 hours gets the first response back (with Idempotent-Replayed: true) instead of running again. 1 to 255 printable ASCII characters, a new value (a UUID) for each request. See https://machinemail.dev/docs/reference#idempotency. |
| `--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-subdomains` | `boolean` |  | Also trust mail signed by subdomains. Default false. Not allowed for an address. Default: `false`. |
| `--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. |
| `--confirm` | `boolean` |  | 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). |
| `--apply-to-existing` | `boolean` |  | Also release mail held over the last 30 days that the new entry now trusts: mail held for sender or authentication-history reasons that carries the domain’s own DKIM signature. Never mail held for malware, instructions to agents or phishing, mail a person quarantined, or mail a block or allow-only scope stops. Released mail emits message.released, not message.received. Default false. Default: `false`. |
| `-d, --data <json|@file|->` | `string` |  | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
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`](https://machinemail.dev/docs/reference/api/trusted-domains#create-trusted-domain)
- [`POST /v0/inboxes/{inbox_id}/trusted-domains`](https://machinemail.dev/docs/reference/api/trusted-domains#create-trusted-domain-in-inbox) with `--inbox`
- [`POST /v0/pods/{pod_id}/trusted-domains`](https://machinemail.dev/docs/reference/api/trusted-domains#create-trusted-domain-in-pod) with `--pod`

## trusted-domains delete

Delete trusted domain.

Also: `machinemail trusted-domains rm`.

Mail from the domain is judged normally again: every message the entry marked trusted gets back the level and labels it would have without it (a large set is finished in the background after the response). Any credential with trusted\_domain\_delete that can see the entry may remove it.

Requires the trusted\_domain\_delete permission.

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

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<trusted-domain-id>` | `string` | required | ID of the entry (td_...). |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Use this inbox's scoped route. |
| `--pod <pod-id>` | `string` |  | Use this pod's scoped route. |

#### Examples

```bash
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}`](https://machinemail.dev/docs/reference/api/trusted-domains#delete-trusted-domain)
- [`DELETE /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id}`](https://machinemail.dev/docs/reference/api/trusted-domains#delete-trusted-domain-in-inbox) with `--inbox`
- [`DELETE /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id}`](https://machinemail.dev/docs/reference/api/trusted-domains#delete-trusted-domain-in-pod) 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.

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

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<trusted-domain-id>` | `string` | required | ID of the entry (td_...). |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Only this inbox. |
| `--pod <pod-id>` | `string` |  | Only this pod. |

#### Examples

```bash
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}`](https://machinemail.dev/docs/reference/api/trusted-domains#get-trusted-domain)
- [`GET /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id}`](https://machinemail.dev/docs/reference/api/trusted-domains#get-trusted-domain-in-inbox) with `--inbox`
- [`GET /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id}`](https://machinemail.dev/docs/reference/api/trusted-domains#get-trusted-domain-in-pod) 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.

```bash
machinemail trusted-domains list [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--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. Default: `50`. |
| `--page-token <value>` | `string` |  | next_page_token from the previous page. |
| `--ascending` | `boolean` |  | Oldest first. |
| `--all` | `boolean` |  | Follow next_page_token and return every page. |

#### Examples

```bash
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`](https://machinemail.dev/docs/reference/api/trusted-domains#list-trusted-domains)
- [`GET /v0/inboxes/{inbox_id}/trusted-domains`](https://machinemail.dev/docs/reference/api/trusted-domains#list-trusted-domains-in-inbox) with `--inbox`
- [`GET /v0/pods/{pod_id}/trusted-domains`](https://machinemail.dev/docs/reference/api/trusted-domains#list-trusted-domains-in-pod) 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, its warnings, the held mail of the last 30 days apply\_to\_existing would release, exact addresses to trust instead of a whole domain, and what MachineMail has seen of the domain (evidence: its own DKIM signature, first contact, a lookalike of a well-known brand or an existing trusted entry, recent authentication failures). For validating as someone types. Read from the most recent mail at this level.

Requires the trusted\_domain\_read permission.

```bash
machinemail trusted-domains preview [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Use this inbox's scoped route. |
| `--pod <pod-id>` | `string` |  | Use this pod's scoped route. |
| `--idempotency-key <value>` | `string` |  | Makes the request safe to retry: a retry with the same key within 24 hours gets the first response back (with Idempotent-Replayed: true) instead of running again. 1 to 255 printable ASCII characters, a new value (a UUID) for each request. See https://machinemail.dev/docs/reference#idempotency. |
| `--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-subdomains` | `boolean` |  | As for create. |
| `-d, --data <json|@file|->` | `string` |  | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
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`](https://machinemail.dev/docs/reference/api/trusted-domains#preview-trusted-domain)
- [`POST /v0/inboxes/{inbox_id}/trusted-domains/preview`](https://machinemail.dev/docs/reference/api/trusted-domains#preview-trusted-domain-in-inbox) with `--inbox`
- [`POST /v0/pods/{pod_id}/trusted-domains/preview`](https://machinemail.dev/docs/reference/api/trusted-domains#preview-trusted-domain-in-pod) with `--pod`

## trusted-domains suggestions

Suggest trusted domains.

Senders this level regularly corresponds with, most messages first: mail received in the last 90 days that carried the sender’s own DKIM signature (verified by MachineMail), and mail sent to them. Leaves out what is already trusted or blocked here. For free-mail providers and platforms where anyone can write the content, the exact address is suggested instead of the domain. Read from the most recent mail at this level.

Requires the trusted\_domain\_read permission.

```bash
machinemail trusted-domains suggestions [flags]
```

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Only this inbox. |
| `--pod <pod-id>` | `string` |  | Only this pod. |
| `--limit <n>` | `integer` |  | Most suggestions to return. Default 10, maximum 50; larger values are capped. Default: `10`. |

#### Examples

```bash
machinemail trusted-domains suggestions
machinemail trusted-domains suggestions --inbox agent@machinemail.dev
```

#### API

- [`GET /v0/trusted-domains/suggestions`](https://machinemail.dev/docs/reference/api/trusted-domains#suggest-trusted-domains)
- [`GET /v0/inboxes/{inbox_id}/trusted-domains/suggestions`](https://machinemail.dev/docs/reference/api/trusted-domains#suggest-trusted-domains-in-inbox) with `--inbox`
- [`GET /v0/pods/{pod_id}/trusted-domains/suggestions`](https://machinemail.dev/docs/reference/api/trusted-domains#suggest-trusted-domains-in-pod) 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 --include-subdomains off rescores the mail from subdomains it marked trusted, as a delete does. Turning it on 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.

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

#### Arguments

| Field | Type | | Description |
| --- | --- | --- | --- |
| `<trusted-domain-id>` | `string` | required | ID of the entry (td_...). |

#### Flags

| Field | Type | | Description |
| --- | --- | --- | --- |
| `--inbox <inbox-id>` | `string` |  | Use this inbox's scoped route. |
| `--pod <pod-id>` | `string` |  | Use this pod's scoped route. |
| `--idempotency-key <value>` | `string` |  | Makes the request safe to retry: a retry with the same key within 24 hours gets the first response back (with Idempotent-Replayed: true) instead of running again. 1 to 255 printable ASCII characters, a new value (a UUID) for each request. See https://machinemail.dev/docs/reference#idempotency. |
| `--include-subdomains` | `boolean` |  | Also trust mail signed by subdomains. Not allowed for an address. |
| `--confirm` | `boolean` |  | 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

```bash
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}`](https://machinemail.dev/docs/reference/api/trusted-domains#update-trusted-domain)
- [`PATCH /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id}`](https://machinemail.dev/docs/reference/api/trusted-domains#update-trusted-domain-in-inbox) with `--inbox`
- [`PATCH /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id}`](https://machinemail.dev/docs/reference/api/trusted-domains#update-trusted-domain-in-pod) with `--pod`