Trusted domains

A trusted domain is a vendor, partner or service you rely on: mail it genuinely signs is labeled TRUSTED, is never marked suspicious or quarantined, and its text and attachments reach your agents in full. Trust changes how mail is judged, never who gets through:

• A block entry that matches the sender, at any level, wins over trust.
• An allow-only scope (one with receive/allow entries) still blocks every sender it does not allow. Adding a trusted domain never opens it.
• Trust applies only to mail that carries a DKIM signature of the trusted domain itself: the signature’s d= must equal the domain (or be a subdomain of it, with include_subdomains). A relaxed DMARC pass, SPF alone or a forwarder’s signature is not enough, so a spoofed From: is judged as usual.
• Malware is still withheld, and instructions aimed at agents are still flagged, whoever sends them.

Trusted domains are a MachineMail addition: AgentMail’s API has no such resource.

Add a trusted domain

curl https://api.machinemail.dev/v0/trusted-domains \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "vendor.example", "reason": "Vendor invoices"}'

{
  "trusted_domain_id": "td_01m5a2k8c00000a1b2c3d4e5f6",
  "entry_type": "domain",
  "domain": "vendor.example",
  "domain_unicode": "vendor.example",
  "include_subdomains": false,
  "scope": "org",
  "pod_id": null,
  "inbox_id": null,
  "reason": "Vendor invoices",
  "expires_at": null,
  "created_by": { "type": "api_key", "id": "key_01m4fy8h140000efvagszh6rpx" },
  "match_count": 0,
  "last_matched_at": null,
  "created_at": "2026-10-19T09:00:00.000Z",
  "updated_at": "2026-10-19T09:00:00.000Z",
  "warnings": []
}

Adding a domain that already exists at the same level returns the existing entry with 200, unchanged. Internationalized names are stored in their ASCII (punycode) form; responses carry both forms, domain and domain_unicode.

Levels

As with lists, the path decides where an entry lives, and mail to an inbox is judged against all three levels together:

Each level supports:

What cannot be trusted

Some names are refused with 422 trusted_domain_not_allowed, because anyone can get mail from them. error.reason says which:

An exact address at a free mail provider, such as alice@gmail.com, can be trusted: the provider stops anyone else sending as that address.

Platforms that need a confirmation

On platforms where anyone can write the content of a message, such as github.com, google.com or slack.com, trusting the domain trusts every user of the platform. Adding one returns 422 confirmation_required (error.reason: "user_content_platform") until you resend with "confirm": true. Usually the better choice is one address, such as notifications@github.com, which needs no confirmation.

The same applies when include_subdomains would cover such a platform: amazon.de with its subdomains includes the marketplace relay marketplace.amazon.de, so it needs "confirm": true, on create or when a PATCH turns include_subdomains on. One address on a group or marketplace relay, such as team@googlegroups.com, needs it too, because whoever posts to the group sends as that address. A domain whose subdomains include a privacy relay or a MachineMail shared domain (appleid.com, which has privaterelay.appleid.com under it) can be trusted only without its subdomains.

Warnings

Conflicts never refuse an entry. When a block entry matches some of the mail an entry would trust, or a scope it applies to is allow-only, the entry is saved and the response lists warnings:

[
  {
    "code": "shadowed_by_block",
    "scope": "inbox",
    "pod_id": "pod_01m4fy8h140000efvagszh6rpx",
    "inbox_id": "support@agents.example",
    "entry": { "entry": "billing.vendor.example", "entry_type": "domain" },
    "message": "The inbox block entry billing.vendor.example still blocks some or all of this mail: a block wins over trust."
  }
]

POST, PATCH and POST .../preview return warnings; GET does not. The block entry itself (entry) is included only for keys that can read lists (list_entry_read).

Who can add trusted domains

A trusted domain hands mail to your agents in full, so adding or changing one takes an organization API key with the permission, or a person in the dashboard. Pod and inbox keys, connected apps and agent access tokens get 403 whatever their permissions, and there is no MCP tool for it: an agent that reads a malicious email cannot be talked into trusting the attacker’s domain.

Limits

The limit counts entries at every level of the organization. Past it, adding one returns 402 plan_limit_exceeded with error.limit_key trusted_domains, error.limit and error.used, like the other plan limits. Remove an entry, or upgrade, to add another.

Events

Every change is recorded in the event log as trusted_domain.created, trusted_domain.updated or trusted_domain.deleted, with the entry (and its created_by) under data.trusted_domain: together they are the audit trail. Webhooks and WebSocket subscriptions receive these events only when their event_types list them.

Next