title: "Trusted Domains" description: "Domains and addresses the organization, a pod or an inbox trusts: mail they genuinely sign is never quarantined or withheld from agents. Preview an entry first." canonical: "https://machinemail.dev/docs/reference/api/trusted-domains"

Trusted Domains

Domains and addresses the organization, a pod or an inbox trusts: mail they genuinely sign is never quarantined or withheld from agents. Preview an entry first.

Source: https://machinemail.dev/docs/reference/api/trusted-domains

List Trusted Domains in Inbox

GET /v0/inboxes/{inbox_id}/trusted-domains

Same as List Trusted Domains (GET /v0/trusted-domains), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Path parameters

Query parameters

Response

200 A page of trusted domains (application/json)

Each item of trusted_domains is a TrustedDomain:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/trusted-domains" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

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

POST /v0/inboxes/{inbox_id}/trusted-domains

Same as Create Trusted Domain (POST /v0/trusted-domains), limited to the inbox.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: trusted_domain_create.

Path parameters

Request body

Content type: application/json.

Response

200 The existing entry for this domain or client_id (application/json)

Each item of warnings is a Warning:

201 Created (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

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

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Path parameters

Request body

Content type: application/json.

Response

200 The preview (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

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

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Path parameters

Response

200 The entry (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/trusted-domains/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Trusted Domain in Inbox

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated entry (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

Delete Trusted Domain in Inbox

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_delete.

Path parameters

Response

204 Deleted

Errors

Error bodies use the error envelope.

Example

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

GET /v0/pods/{pod_id}/trusted-domains

Same as List Trusted Domains (GET /v0/trusted-domains), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Path parameters

Query parameters

Response

200 A page of trusted domains (application/json)

Each item of trusted_domains is a TrustedDomain:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Create Trusted Domain in Pod

POST /v0/pods/{pod_id}/trusted-domains

Same as Create Trusted Domain (POST /v0/trusted-domains), limited to the pod.

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: trusted_domain_create.

Path parameters

Request body

Content type: application/json.

Response

200 The existing entry for this domain or client_id (application/json)

Each item of warnings is a Warning:

201 Created (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

Preview Trusted Domain in Pod

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Path parameters

Request body

Content type: application/json.

Response

200 The preview (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

Get Trusted Domain in Pod

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Path parameters

Response

200 The entry (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Trusted Domain in Pod

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated entry (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

Delete Trusted Domain in Pod

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_delete.

Path parameters

Response

204 Deleted

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/trusted-domains/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

List Trusted Domains

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Query parameters

Response

200 A page of trusted domains (application/json)

Each item of trusted_domains is a TrustedDomain:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/trusted-domains" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Create Trusted Domain

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_create.

Request body

Content type: application/json.

Response

200 The existing entry for this domain or client_id (application/json)

Each item of warnings is a Warning:

201 Created (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

Preview Trusted Domain

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Request body

Content type: application/json.

Response

200 The preview (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

Get Trusted Domain

GET /v0/trusted-domains/{trusted_domain_id}

An entry stored at this level (404 for entries at another level).

Authentication: Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: trusted_domain_read.

Path parameters

Response

200 The entry (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/v0/trusted-domains/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Update Trusted Domain

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_update.

Path parameters

Request body

Content type: application/json.

Response

200 The updated entry (application/json)

Each item of warnings is a Warning:

Errors

Error bodies use the error envelope.

Example

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"
}'

Delete Trusted Domain

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 <api key> or the dashboard mm_session cookie. Permission: trusted_domain_delete.

Path parameters

Response

204 Deleted

Errors

Error bodies use the error envelope.

Example

curl -X DELETE "https://api.machinemail.dev/v0/trusted-domains/string" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"