Trusted Domains · MachineMail Docs

Skip to content Skip to content

[01/18]List Trusted Domains in Inbox

List Trusted Domains in Inbox

http

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

FieldDescription

inbox_id``stringRequired

ID of the inbox.

Query parameters

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

200 A page of trusted domains (application/json)

FieldDescription

count``integerRequired

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[] 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:

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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

Error bodies use the error envelope.

Example

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

http

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

FieldDescription

inbox_id``stringRequired

ID of the inbox.

Request body

Content type: application/json.

FieldDescription

domain``stringRequired

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

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

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

201 Created (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox.

Request body

Content type: application/json.

FieldDescription

domain``stringRequired

include_subdomains``boolean

As for create.

Response

200 The preview (application/json)

FieldDescription

domain``string | nullRequired

The entry as it would be stored (ASCII form). null when it is not a domain or address.

domain_unicode``string | nullRequired

The same in Unicode form.

entry_type``objectRequired

allowed``booleanRequired

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

Why it cannot be trusted. null when it can.

message``string | nullRequired

The refusal or confirmation, in one sentence. null when there is neither.

confirmation_required``booleanRequired

A platform where anyone can write the content, or a relay address: a create needs confirm: true.

warnings Warning[] Required

Conflicts with block entries or allow-only scopes, as a create would report them.

would_release``object | nullRequired

Not computed yet: always null.

suggestions``string[] | nullRequired

Narrower entries to consider (an exact address). Not computed yet: always null.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox.

trusted_domain_id``stringRequired

ID of the entry (td_...).

Response

200 The entry (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox.

trusted_domain_id``stringRequired

ID of the entry (td_...).

Request body

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

200 The updated entry (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox.

trusted_domain_id``stringRequired

ID of the entry (td_...).

Response

204 Deleted

Errors

Error bodies use the error envelope.

Example

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

http

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

FieldDescription

pod_id``stringRequired

ID of the pod.

Query parameters

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

200 A page of trusted domains (application/json)

FieldDescription

count``integerRequired

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[] 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:

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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

Error bodies use the error envelope.

Example

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

http

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

FieldDescription

pod_id``stringRequired

ID of the pod.

Request body

Content type: application/json.

FieldDescription

domain``stringRequired

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

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

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

201 Created (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

Request body

Content type: application/json.

FieldDescription

domain``stringRequired

include_subdomains``boolean

As for create.

Response

200 The preview (application/json)

FieldDescription

domain``string | nullRequired

The entry as it would be stored (ASCII form). null when it is not a domain or address.

domain_unicode``string | nullRequired

The same in Unicode form.

entry_type``objectRequired

allowed``booleanRequired

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

Why it cannot be trusted. null when it can.

message``string | nullRequired

The refusal or confirmation, in one sentence. null when there is neither.

confirmation_required``booleanRequired

A platform where anyone can write the content, or a relay address: a create needs confirm: true.

warnings Warning[] Required

Conflicts with block entries or allow-only scopes, as a create would report them.

would_release``object | nullRequired

Not computed yet: always null.

suggestions``string[] | nullRequired

Narrower entries to consider (an exact address). Not computed yet: always null.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

trusted_domain_id``stringRequired

ID of the entry (td_...).

Response

200 The entry (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

trusted_domain_id``stringRequired

ID of the entry (td_...).

Request body

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

200 The updated entry (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

trusted_domain_id``stringRequired

ID of the entry (td_...).

Response

204 Deleted

Errors

Error bodies use the error envelope.

Example

Request

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

List Trusted Domains

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

Query parameters

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

200 A page of trusted domains (application/json)

FieldDescription

count``integerRequired

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[] 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:

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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

Error bodies use the error envelope.

Example

Request

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

Response 200

Create Trusted Domain

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

Request body

Content type: application/json.

FieldDescription

domain``stringRequired

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

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

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

201 Created (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

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

Request body

Content type: application/json.

FieldDescription

domain``stringRequired

include_subdomains``boolean

As for create.

Response

200 The preview (application/json)

FieldDescription

domain``string | nullRequired

The entry as it would be stored (ASCII form). null when it is not a domain or address.

domain_unicode``string | nullRequired

The same in Unicode form.

entry_type``objectRequired

allowed``booleanRequired

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

Why it cannot be trusted. null when it can.

message``string | nullRequired

The refusal or confirmation, in one sentence. null when there is neither.

confirmation_required``booleanRequired

A platform where anyone can write the content, or a relay address: a create needs confirm: true.

warnings Warning[] Required

Conflicts with block entries or allow-only scopes, as a create would report them.

would_release``object | nullRequired

Not computed yet: always null.

suggestions``string[] | nullRequired

Narrower entries to consider (an exact address). Not computed yet: always null.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

http

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

FieldDescription

trusted_domain_id``stringRequired

ID of the entry (td_...).

Response

200 The entry (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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

Error bodies use the error envelope.

Example

Request

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

Response 200

Update Trusted Domain

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

Path parameters

FieldDescription

trusted_domain_id``stringRequired

ID of the entry (td_...).

Request body

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

200 The updated entry (application/json)

FieldDescription

trusted_domain_id``stringRequired

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

The domain, or for entry_type: "email" the address, lowercased, with the domain in its ASCII (punycode) form.

domain_unicode``stringRequired

The same, with the domain in its Unicode form. Equal to domain for ASCII names.

include_subdomains``booleanRequired

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

The pod, for pod- and inbox-scoped entries.

inbox_id``string | nullRequired

The inbox, for inbox-scoped entries.

reason``string | nullRequired

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

expires_at``string (date-time) | nullRequired

When the entry stops applying. null: never.

created_by``object | nullRequired

Who added the entry.

match_count``integerRequired

Messages this entry has marked trusted.

last_matched_at``string (date-time) | nullRequired

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[] Required

Conflicts with block entries or allow-only scopes. Empty when there are none.

Each item of warnings is a Warning:

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

What the warning means, in one sentence.

Errors

Error bodies use the error envelope.

Example

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

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

Path parameters

FieldDescription

trusted_domain_id``stringRequired

ID of the entry (td_...).

Response

204 Deleted

Errors

Error bodies use the error envelope.

Example

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 Create Trusted Domain in Inbox Preview Trusted Domain in Inbox Get Trusted Domain in Inbox Update Trusted Domain in Inbox Delete Trusted Domain in Inbox List Trusted Domains in Pod Create Trusted Domain in Pod Preview Trusted Domain in Pod Get Trusted Domain in Pod Update Trusted Domain in Pod Delete Trusted Domain in Pod List Trusted Domains Create Trusted Domain Preview Trusted Domain Get Trusted Domain Update Trusted Domain Delete Trusted Domain

100% readTop