[Skip to content](/content/docs/reference/api/trusted-domains#nd-page/index.html) [Skip to content](/content/docs/reference/api/trusted-domains#nd-page/index.html) \[01/18\]List Trusted Domains in Inbox | Method | Path | Summary | | --- | --- | --- | | `GET` | `/v0/inboxes/{inbox_id}/trusted-domains` | [List Trusted Domains in Inbox](/content/docs/reference/api/trusted-domains#list-trusted-domains-in-inbox/index.html) | | `POST` | `/v0/inboxes/{inbox_id}/trusted-domains` | [Create Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#create-trusted-domain-in-inbox/index.html) | | `POST` | `/v0/inboxes/{inbox_id}/trusted-domains/preview` | [Preview Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#preview-trusted-domain-in-inbox/index.html) | | `GET` | `/v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id}` | [Get Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#get-trusted-domain-in-inbox/index.html) | | `PATCH` | `/v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id}` | [Update Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#update-trusted-domain-in-inbox/index.html) | | `DELETE` | `/v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id}` | [Delete Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#delete-trusted-domain-in-inbox/index.html) | | `GET` | `/v0/pods/{pod_id}/trusted-domains` | [List Trusted Domains in Pod](/content/docs/reference/api/trusted-domains#list-trusted-domains-in-pod/index.html) | | `POST` | `/v0/pods/{pod_id}/trusted-domains` | [Create Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#create-trusted-domain-in-pod/index.html) | | `POST` | `/v0/pods/{pod_id}/trusted-domains/preview` | [Preview Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#preview-trusted-domain-in-pod/index.html) | | `GET` | `/v0/pods/{pod_id}/trusted-domains/{trusted_domain_id}` | [Get Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#get-trusted-domain-in-pod/index.html) | | `PATCH` | `/v0/pods/{pod_id}/trusted-domains/{trusted_domain_id}` | [Update Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#update-trusted-domain-in-pod/index.html) | | `DELETE` | `/v0/pods/{pod_id}/trusted-domains/{trusted_domain_id}` | [Delete Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#delete-trusted-domain-in-pod/index.html) | | `GET` | `/v0/trusted-domains` | [List Trusted Domains](/content/docs/reference/api/trusted-domains#list-trusted-domains/index.html) | | `POST` | `/v0/trusted-domains` | [Create Trusted Domain](/content/docs/reference/api/trusted-domains#create-trusted-domain/index.html) | | `POST` | `/v0/trusted-domains/preview` | [Preview Trusted Domain](/content/docs/reference/api/trusted-domains#preview-trusted-domain/index.html) | | `GET` | `/v0/trusted-domains/{trusted_domain_id}` | [Get Trusted Domain](/content/docs/reference/api/trusted-domains#get-trusted-domain/index.html) | | `PATCH` | `/v0/trusted-domains/{trusted_domain_id}` | [Update Trusted Domain](/content/docs/reference/api/trusted-domains#update-trusted-domain/index.html) | | `DELETE` | `/v0/trusted-domains/{trusted_domain_id}` | [Delete Trusted Domain](/content/docs/reference/api/trusted-domains#delete-trusted-domain/index.html) | ## [List Trusted Domains in Inbox](/content/docs/reference/api/trusted-domains\#list-trusted-domains-in-inbox/index.html) http ``` GET /v0/inboxes/{inbox_id}/trusted-domains ``` Same as List Trusted Domains (`GET /v0/trusted-domains`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. #### [Query parameters](/content/docs/reference/api/trusted-domains\#query-parameters/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Oldest first. #### [Response](/content/docs/reference/api/trusted-domains\#response/index.html) **200** A page of trusted domains (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `trusted_domains` [TrustedDomain\[\]](/content/docs/reference/api/objects#trusteddomain/index.html) Required Entries stored at exactly this level (organization, pod or inbox), newest first unless ascending is set. Each item of `trusted_domains` is a [TrustedDomain](/content/docs/reference/api/objects#trusteddomain/index.html): FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. #### [Errors](/content/docs/reference/api/trusted-domains\#errors/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `404` | Not found. Also returned for resources outside the credential scope. | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example/index.html) Request ``` curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/trusted-domains" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "count": 1, "limit": 50, "next_page_token": "eyJvIjo1MH0", "trusted_domains": [\ {\ "trusted_domain_id": "string",\ "entry_type": "domain",\ "domain": "example.com",\ "domain_unicode": "string",\ "include_subdomains": false,\ "scope": "org",\ "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",\ "inbox_id": "agent@machinemail.dev",\ "reason": "string",\ "expires_at": "2026-10-01T12:00:00.000Z",\ "created_by": {\ "type": "user",\ "id": "string"\ },\ "match_count": 1,\ "last_matched_at": "2026-10-01T12:00:00.000Z",\ "created_at": "2026-10-01T12:00:00.000Z",\ "updated_at": "2026-10-01T12:00:00.000Z"\ }\ ] } ``` ## [Create Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains\#create-trusted-domain-in-inbox/index.html) http ``` POST /v0/inboxes/{inbox_id}/trusted-domains ``` Same as Create Trusted Domain (`POST /v0/trusted-domains`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_create`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-1/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. #### [Request body](/content/docs/reference/api/trusted-domains\#request-body/index.html) Content type: `application/json`. FieldDescription `domain``string`Required A domain (example.com) or an exact address (invoices@example.com). Unicode names are accepted and stored in ASCII (punycode) form. (min length 1, max length 320) `include_subdomains``boolean` Also trust mail signed by subdomains. Default false. Not allowed for an address. `reason``string` Why you trust it, for people reading the list. Never included in a message’s trust report. (max length 500) `expires_at``string (date-time)` 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``string` Idempotency key: a create with a client\_id already used in the organization returns that entry (200). #### [Response](/content/docs/reference/api/trusted-domains\#response-1/index.html) **200** The existing entry for this domain or client\_id (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required shadowed\_by\_block: a receive/block list entry matches some or all of the mail this entry trusts, and a block always wins over trust. shadowed\_by\_allow\_only: the scope is allow-only (it has receive/allow entries) and none of them allows this sender, so the mail is still BLOCKED. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. **201** Created (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-1/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `402` | The organization already has as many trusted domains as its plan allows (limit\_key: “trusted\_domains”): 10 on Free, 500 on paid plans, none for unclaimed sandbox agents. Remove one first. | | `403` | The credential lacks trusted\_domain\_create, or is not an organization API key or a dashboard session. 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. | | `404` | Not found. Also returned for resources outside the credential scope. | | `409` | client\_id is already used at another level. | | `422` | trusted\_domain\_not\_allowed (with error.reason) or confirmation\_required (resend with confirm: true). | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-1/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/trusted-domains" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com", "reason": "string" }' ``` Response 200 ``` { "trusted_domain_id": "string", "entry_type": "domain", "domain": "example.com", "domain_unicode": "string", "include_subdomains": false, "scope": "org", "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f", "inbox_id": "agent@machinemail.dev", "reason": "string", "expires_at": "2026-10-01T12:00:00.000Z", "created_by": { "type": "user", "id": "string" }, "match_count": 1, "last_matched_at": "2026-10-01T12:00:00.000Z", "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-01T12:00:00.000Z", "warnings": [\ {\ "code": "shadowed_by_block",\ "scope": "org",\ "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",\ "inbox_id": "agent@machinemail.dev",\ "entry": {\ "entry": "customer@example.com",\ "entry_type": "email"\ },\ "message": "string"\ }\ ] } ``` ## [Preview Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains\#preview-trusted-domain-in-inbox/index.html) http ``` POST /v0/inboxes/{inbox_id}/trusted-domains/preview ``` Same as Preview Trusted Domain (`POST /v0/trusted-domains/preview`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-2/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. #### [Request body](/content/docs/reference/api/trusted-domains\#request-body-1/index.html) Content type: `application/json`. FieldDescription `domain``string`Required `include_subdomains``boolean` As for create. #### [Response](/content/docs/reference/api/trusted-domains\#response-2/index.html) **200** The preview (`application/json`) FieldDescription `domain``string | null`Required The entry as it would be stored (ASCII form). null when it is not a domain or address. `domain_unicode``string | null`Required The same in Unicode form. `entry_type``object`Required `allowed``boolean`Required Whether a create would be accepted (with confirm: true when confirmation\_required), plan limit aside. `refusal``("free_mail" | "privacy_relay" | "shared_platform" | "public_suffix" | "disposable" | "invalid" | "confusable_idn" | null) | null`Required Why it cannot be trusted. null when it can. `message``string | null`Required The refusal or confirmation, in one sentence. null when there is neither. `confirmation_required``boolean`Required A platform where anyone can write the content, or a relay address: a create needs confirm: true. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes, as a create would report them. `would_release``object | null`Required Not computed yet: always null. `suggestions``string[] | null`Required Narrower entries to consider (an exact address). Not computed yet: always null. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-2/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-2/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/trusted-domains/preview" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com" }' ``` Response 200 ``` { "domain": "example.com", "domain_unicode": "string", "entry_type": {}, "allowed": false, "refusal": "free_mail", "message": "string", "confirmation_required": false, "warnings": [\ {\ "code": "shadowed_by_block",\ "scope": "org",\ "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",\ "inbox_id": "agent@machinemail.dev",\ "entry": {\ "entry": "customer@example.com",\ "entry_type": "email"\ },\ "message": "string"\ }\ ], "would_release": { "count": 1 }, "suggestions": ["string"] } ``` ## [Get Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains\#get-trusted-domain-in-inbox/index.html) http ``` GET /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id} ``` Same as Get Trusted Domain (`GET /v0/trusted-domains/{trusted_domain_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-3/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Response](/content/docs/reference/api/trusted-domains\#response-3/index.html) **200** The entry (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-3/index.html) | Status | Meaning | | --- | --- | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `404` | Not found. Also returned for resources outside the credential scope. | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-3/index.html) Request ``` curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ``` { "trusted_domain_id": "string", "entry_type": "domain", "domain": "example.com", "domain_unicode": "string", "include_subdomains": false, "scope": "org", "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f", "inbox_id": "agent@machinemail.dev", "reason": "string", "expires_at": "2026-10-01T12:00:00.000Z", "created_by": { "type": "user", "id": "string" }, "match_count": 1, "last_matched_at": "2026-10-01T12:00:00.000Z", "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-01T12:00:00.000Z" } ``` ## [Update Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains\#update-trusted-domain-in-inbox/index.html) http ``` PATCH /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id} ``` Same as Update Trusted Domain (`PATCH /v0/trusted-domains/{trusted_domain_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_update`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-4/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Request body](/content/docs/reference/api/trusted-domains\#request-body-2/index.html) Content type: `application/json`. FieldDescription `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``string | null` New reason; null clears it. (max length 500) `expires_at``string (date-time) | null` New expiry, in the future; null removes it. #### [Response](/content/docs/reference/api/trusted-domains\#response-4/index.html) **200** The updated entry (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-4/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks trusted\_domain\_update, or is not an organization API key or a dashboard session. 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. | | `404` | Not found. Also returned for resources outside the credential scope. | | `422` | Turning on include\_subdomains: trusted\_domain\_not\_allowed (with error.reason) or confirmation\_required (resend with confirm: true). | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-4/index.html) Request ``` curl -X PATCH "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reason": "string" }' ``` Response 200 ## [Delete Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains\#delete-trusted-domain-in-inbox/index.html) http ``` DELETE /v0/inboxes/{inbox_id}/trusted-domains/{trusted_domain_id} ``` Same as Delete Trusted Domain (`DELETE /v0/trusted-domains/{trusted_domain_id}`), limited to the inbox. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_delete`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-5/index.html) FieldDescription `inbox_id``string`Required ID of the inbox. `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Response](/content/docs/reference/api/trusted-domains\#response-5/index.html) **204** Deleted #### [Errors](/content/docs/reference/api/trusted-domains\#errors-5/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-5/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` ## [List Trusted Domains in Pod](/content/docs/reference/api/trusted-domains\#list-trusted-domains-in-pod/index.html) http ``` GET /v0/pods/{pod_id}/trusted-domains ``` Same as List Trusted Domains (`GET /v0/trusted-domains`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-6/index.html) FieldDescription `pod_id``string`Required ID of the pod. #### [Query parameters](/content/docs/reference/api/trusted-domains\#query-parameters-1/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Oldest first. #### [Response](/content/docs/reference/api/trusted-domains\#response-6/index.html) **200** A page of trusted domains (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `trusted_domains` [TrustedDomain\[\]](/content/docs/reference/api/objects#trusteddomain/index.html) Required Entries stored at exactly this level (organization, pod or inbox), newest first unless ascending is set. Each item of `trusted_domains` is a [TrustedDomain](/content/docs/reference/api/objects#trusteddomain/index.html): FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-6/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-6/index.html) Request ``` curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Create Trusted Domain in Pod](/content/docs/reference/api/trusted-domains\#create-trusted-domain-in-pod/index.html) http ``` POST /v0/pods/{pod_id}/trusted-domains ``` Same as Create Trusted Domain (`POST /v0/trusted-domains`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_create`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-7/index.html) FieldDescription `pod_id``string`Required ID of the pod. #### [Request body](/content/docs/reference/api/trusted-domains\#request-body-3/index.html) Content type: `application/json`. FieldDescription `domain``string`Required `include_subdomains``boolean` Also trust mail signed by subdomains. Default false. Not allowed for an address. `reason``string` Why you trust it, for people reading the list. Never included in a message’s trust report. (max length 500) `expires_at``string (date-time)` When the entry stops applying. Must be in the future. Omit for never. `confirm``boolean` `client_id``string` Idempotency key: a create with a client\_id already used in the organization returns that entry (200). #### [Response](/content/docs/reference/api/trusted-domains\#response-7/index.html) **200** The existing entry for this domain or client\_id (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. **201** Created (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-7/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-7/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com", "reason": "string" }' ``` Response 200 ## [Preview Trusted Domain in Pod](/content/docs/reference/api/trusted-domains\#preview-trusted-domain-in-pod/index.html) http ``` POST /v0/pods/{pod_id}/trusted-domains/preview ``` Same as Preview Trusted Domain (`POST /v0/trusted-domains/preview`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-8/index.html) FieldDescription `pod_id``string`Required ID of the pod. #### [Request body](/content/docs/reference/api/trusted-domains\#request-body-4/index.html) Content type: `application/json`. FieldDescription `domain``string`Required `include_subdomains``boolean` As for create. #### [Response](/content/docs/reference/api/trusted-domains\#response-8/index.html) **200** The preview (`application/json`) FieldDescription `domain``string | null`Required The entry as it would be stored (ASCII form). null when it is not a domain or address. `domain_unicode``string | null`Required The same in Unicode form. `entry_type``object`Required `allowed``boolean`Required Whether a create would be accepted (with confirm: true when confirmation\_required), plan limit aside. `refusal``("free_mail" | "privacy_relay" | "shared_platform" | "public_suffix" | "disposable" | "invalid" | "confusable_idn" | null) | null`Required Why it cannot be trusted. null when it can. `message``string | null`Required The refusal or confirmation, in one sentence. null when there is neither. `confirmation_required``boolean`Required A platform where anyone can write the content, or a relay address: a create needs confirm: true. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes, as a create would report them. `would_release``object | null`Required Not computed yet: always null. `suggestions``string[] | null`Required Narrower entries to consider (an exact address). Not computed yet: always null. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-8/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-8/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains/preview" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com" }' ``` Response 200 ## [Get Trusted Domain in Pod](/content/docs/reference/api/trusted-domains\#get-trusted-domain-in-pod/index.html) http ``` GET /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id} ``` Same as Get Trusted Domain (`GET /v0/trusted-domains/{trusted_domain_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-9/index.html) FieldDescription `pod_id``string`Required ID of the pod. `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Response](/content/docs/reference/api/trusted-domains\#response-9/index.html) **200** The entry (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-9/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-9/index.html) Request ``` curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Update Trusted Domain in Pod](/content/docs/reference/api/trusted-domains\#update-trusted-domain-in-pod/index.html) http ``` PATCH /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id} ``` Same as Update Trusted Domain (`PATCH /v0/trusted-domains/{trusted_domain_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_update`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-10/index.html) FieldDescription `pod_id``string`Required ID of the pod. `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Request body](/content/docs/reference/api/trusted-domains\#request-body-5/index.html) Content type: `application/json`. FieldDescription `include_subdomains``boolean` Also trust mail signed by subdomains. Not allowed for an address. `confirm``boolean` `reason``string | null` New reason; null clears it. (max length 500) `expires_at``string (date-time) | null` New expiry, in the future; null removes it. #### [Response](/content/docs/reference/api/trusted-domains\#response-10/index.html) **200** The updated entry (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-10/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-10/index.html) Request ``` curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reason": "string" }' ``` Response 200 ## [Delete Trusted Domain in Pod](/content/docs/reference/api/trusted-domains\#delete-trusted-domain-in-pod/index.html) http ``` DELETE /v0/pods/{pod_id}/trusted-domains/{trusted_domain_id} ``` Same as Delete Trusted Domain (`DELETE /v0/trusted-domains/{trusted_domain_id}`), limited to the pod. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_delete`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-11/index.html) FieldDescription `pod_id``string`Required ID of the pod. `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Response](/content/docs/reference/api/trusted-domains\#response-11/index.html) **204** Deleted #### [Errors](/content/docs/reference/api/trusted-domains\#errors-11/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-11/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` ## [List Trusted Domains](/content/docs/reference/api/trusted-domains\#list-trusted-domains/index.html) http ``` GET /v0/trusted-domains ``` 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. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Query parameters](/content/docs/reference/api/trusted-domains\#query-parameters-2/index.html) FieldDescription `limit``integer` Maximum number of items to return. Default 50, maximum 500; larger values are capped. `page_token``string` next\_page\_token from the previous page. `ascending``boolean` Oldest first. #### [Response](/content/docs/reference/api/trusted-domains\#response-12/index.html) **200** A page of trusted domains (`application/json`) FieldDescription `count``integer`Required Number of items returned. `limit``integer` Maximum number of items per page. Default 50, maximum 500; larger values are capped. `next_page_token``string` Page token for pagination. Absent on the last page. `trusted_domains` [TrustedDomain\[\]](/content/docs/reference/api/objects#trusteddomain/index.html) Required Entries stored at exactly this level (organization, pod or inbox), newest first unless ascending is set. Each item of `trusted_domains` is a [TrustedDomain](/content/docs/reference/api/objects#trusteddomain/index.html): FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-12/index.html) | Status | Meaning | | --- | --- | | `400` | Invalid request: error.type is validation and error.param names the field. | | `401` | Missing, invalid, expired or revoked credential. | | `403` | The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account\_suspended: error.message says what still works; do not retry or re-register). | | `500` | Unexpected server error. | Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-12/index.html) Request ``` curl "https://api.machinemail.dev/v0/trusted-domains" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Create Trusted Domain](/content/docs/reference/api/trusted-domains\#create-trusted-domain/index.html) http ``` POST /v0/trusted-domains ``` 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: true`. 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. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_create`. #### [Request body](/content/docs/reference/api/trusted-domains\#request-body-6/index.html) Content type: `application/json`. FieldDescription `domain``string`Required `include_subdomains``boolean` Also trust mail signed by subdomains. Default false. Not allowed for an address. `reason``string` Why you trust it, for people reading the list. Never included in a message’s trust report. (max length 500) `expires_at``string (date-time)` When the entry stops applying. Must be in the future. Omit for never. `confirm``boolean` `client_id``string` Idempotency key: a create with a client\_id already used in the organization returns that entry (200). #### [Response](/content/docs/reference/api/trusted-domains\#response-13/index.html) **200** The existing entry for this domain or client\_id (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. **201** Created (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-13/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-13/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/trusted-domains" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com", "reason": "string" }' ``` Response 200 ## [Preview Trusted Domain](/content/docs/reference/api/trusted-domains\#preview-trusted-domain/index.html) http ``` POST /v0/trusted-domains/preview ``` 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`. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Request body](/content/docs/reference/api/trusted-domains\#request-body-7/index.html) Content type: `application/json`. FieldDescription `domain``string`Required `include_subdomains``boolean` As for create. #### [Response](/content/docs/reference/api/trusted-domains\#response-14/index.html) **200** The preview (`application/json`) FieldDescription `domain``string | null`Required The entry as it would be stored (ASCII form). null when it is not a domain or address. `domain_unicode``string | null`Required The same in Unicode form. `entry_type``object`Required `allowed``boolean`Required Whether a create would be accepted (with confirm: true when confirmation\_required), plan limit aside. `refusal``("free_mail" | "privacy_relay" | "shared_platform" | "public_suffix" | "disposable" | "invalid" | "confusable_idn" | null) | null`Required Why it cannot be trusted. null when it can. `message``string | null`Required The refusal or confirmation, in one sentence. null when there is neither. `confirmation_required``boolean`Required A platform where anyone can write the content, or a relay address: a create needs confirm: true. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes, as a create would report them. `would_release``object | null`Required Not computed yet: always null. `suggestions``string[] | null`Required Narrower entries to consider (an exact address). Not computed yet: always null. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-14/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-14/index.html) Request ``` curl -X POST "https://api.machinemail.dev/v0/trusted-domains/preview" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com" }' ``` Response 200 ## [Get Trusted Domain](/content/docs/reference/api/trusted-domains\#get-trusted-domain/index.html) http ``` GET /v0/trusted-domains/{trusted_domain_id} ``` An entry stored at this level (`404` for entries at another level). **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_read`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-12/index.html) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Response](/content/docs/reference/api/trusted-domains\#response-15/index.html) **200** The entry (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-15/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-15/index.html) Request ``` curl "https://api.machinemail.dev/v0/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` Response 200 ## [Update Trusted Domain](/content/docs/reference/api/trusted-domains\#update-trusted-domain/index.html) http ``` PATCH /v0/trusted-domains/{trusted_domain_id} ``` 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: true` 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. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_update`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-13/index.html) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Request body](/content/docs/reference/api/trusted-domains\#request-body-8/index.html) Content type: `application/json`. FieldDescription `include_subdomains``boolean` Also trust mail signed by subdomains. Not allowed for an address. `confirm``boolean` `reason``string | null` New reason; null clears it. (max length 500) `expires_at``string (date-time) | null` New expiry, in the future; null removes it. #### [Response](/content/docs/reference/api/trusted-domains\#response-16/index.html) **200** The updated entry (`application/json`) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). `entry_type``"domain" | "email"`Required domain: every address at the domain (and its subdomains with include\_subdomains). email: exactly one address. `domain``string`Required The domain, or for entry\_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form. `domain_unicode``string`Required The same, with the domain in its Unicode form. Equal to domain for ASCII names. `include_subdomains``boolean`Required Also trust mail signed by subdomains (billing.example.com for example.com). Always false for addresses. `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string | null`Required The pod, for pod- and inbox-scoped entries. `inbox_id``string | null`Required The inbox, for inbox-scoped entries. `reason``string | null`Required Why it was added, for people reading the list. Never included in a message’s trust report. `expires_at``string (date-time) | null`Required When the entry stops applying. null: never. `created_by``object | null`Required Who added the entry. `match_count``integer`Required Messages this entry has marked trusted. `last_matched_at``string (date-time) | null`Required When this entry last marked a message trusted. null: never. `created_at``string (date-time)`Required When the entry was added. `updated_at``string (date-time)`Required When the entry last changed. `warnings` [Warning\[\]](/content/docs/reference/api/objects#warning/index.html) Required Conflicts with block entries or allow-only scopes. Empty when there are none. Each item of `warnings` is a [Warning](/content/docs/reference/api/objects#warning/index.html): FieldDescription `code``"shadowed_by_block" | "shadowed_by_allow_only"`Required `scope``"org" | "pod" | "inbox"`Required Where an entry applies: the whole organization, one pod, or one inbox. `pod_id``string` The pod of the list, for pod and inbox scopes. `inbox_id``string` The inbox of the list, for the inbox scope. `entry``object` shadowed\_by\_block only: the block entry. Left out for credentials without list\_entry\_read. `message``string`Required What the warning means, in one sentence. #### [Errors](/content/docs/reference/api/trusted-domains\#errors-16/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-16/index.html) Request ``` curl -X PATCH "https://api.machinemail.dev/v0/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reason": "string" }' ``` Response 200 ## [Delete Trusted Domain](/content/docs/reference/api/trusted-domains\#delete-trusted-domain/index.html) http ``` DELETE /v0/trusted-domains/{trusted_domain_id} ``` 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. **Authentication:**`Authorization: Bearer ` or the dashboard `mm_session` cookie. Permission: `trusted_domain_delete`. #### [Path parameters](/content/docs/reference/api/trusted-domains\#path-parameters-14/index.html) FieldDescription `trusted_domain_id``string`Required ID of the entry (td\_...). #### [Response](/content/docs/reference/api/trusted-domains\#response-17/index.html) **204** Deleted #### [Errors](/content/docs/reference/api/trusted-domains\#errors-17/index.html) Error bodies use the [error envelope](/content/docs/reference/errors/index.html). #### [Example](/content/docs/reference/api/trusted-domains\#example-17/index.html) Request ``` curl -X DELETE "https://api.machinemail.dev/v0/trusted-domains/string" \ -H "Authorization: Bearer $MACHINEMAIL_API_KEY" ``` On this page [List Trusted Domains in Inbox](/content/docs/reference/api/trusted-domains#list-trusted-domains-in-inbox/index.html) [Create Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#create-trusted-domain-in-inbox/index.html) [Preview Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#preview-trusted-domain-in-inbox/index.html) [Get Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#get-trusted-domain-in-inbox/index.html) [Update Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#update-trusted-domain-in-inbox/index.html) [Delete Trusted Domain in Inbox](/content/docs/reference/api/trusted-domains#delete-trusted-domain-in-inbox/index.html) [List Trusted Domains in Pod](/content/docs/reference/api/trusted-domains#list-trusted-domains-in-pod/index.html) [Create Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#create-trusted-domain-in-pod/index.html) [Preview Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#preview-trusted-domain-in-pod/index.html) [Get Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#get-trusted-domain-in-pod/index.html) [Update Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#update-trusted-domain-in-pod/index.html) [Delete Trusted Domain in Pod](/content/docs/reference/api/trusted-domains#delete-trusted-domain-in-pod/index.html) [List Trusted Domains](/content/docs/reference/api/trusted-domains#list-trusted-domains/index.html) [Create Trusted Domain](/content/docs/reference/api/trusted-domains#create-trusted-domain/index.html) [Preview Trusted Domain](/content/docs/reference/api/trusted-domains#preview-trusted-domain/index.html) [Get Trusted Domain](/content/docs/reference/api/trusted-domains#get-trusted-domain/index.html) [Update Trusted Domain](/content/docs/reference/api/trusted-domains#update-trusted-domain/index.html) [Delete Trusted Domain](/content/docs/reference/api/trusted-domains#delete-trusted-domain/index.html) 100% readTop