Control who can email your agent

Allow and block lists control who can email your agent and who it can email. An entry is a full address (partner@example.com) or domain (example.com); each list has a direction (send, receive, or reply) and type (allow or block).

Choose the list

AgentMail resolves an inbound message’s In-Reply-To header against existing inbox threads. Replies to a message the inbox sent use only reply lists; new threads use only receive lists. For example, restrict receive to your domain while leaving reply lists empty to accept replies to the agent’s outbound messages.

Set the scope

Lists exist at inbox, pod, and organization scope. AgentMail checks inbox (/inboxes/{inbox_id}/lists/...), then pod (/pods/{pod_id}/lists/...), then organization (/lists/...); the first match wins. At one scope, it checks exact email before domain, and allow before block. An inbox allow entry for alice@example.com therefore takes precedence over an organization block for example.com.

If an allow list for a direction has entries at any scanned scope, an unmatched sender or recipient is blocked with reason not in allow list. One organization-level receive allow entry makes new inbound mail default-deny for every inbox in that organization.

On /v0/lists/..., the API key determines scope: organization keys manage organization lists, pod keys manage that pod’s lists, and inbox keys manage that inbox’s lists. /pods/{pod_id}/... and /inboxes/{inbox_id}/... set scope explicitly.

Add and remove entries

Create an entry with its direction, type, and address or domain. The optional reason (up to 1,024 characters) is stored with the entry.

# Organization scope: accept new inbound mail only from your company
agentmail lists create \
  --direction receive \
  --type allow \
  --entry yourcompany.com

# Inbox scope: block one sender
agentmail inboxes:lists create \
  --inbox-id agent@yourdomain.com \
  --direction receive \
  --type block \
  --entry noise@example.com \
  --reason "automated newsletter"

{
  "entry": "noise@example.com",
  "entry_type": "email",
  "direction": "receive",
  "list_type": "block",
  "reason": "automated newsletter",
  "organization_id": "<organization_id>",
  "created_at": "2026-07-30T09:12:44Z"
}

Entries containing @ come back as entry_type: "email"; all others as "domain". The reason is echoed whenever this entry blocks something.

Delete an entry on the same path. Deletion returns 204 and applies to the next send or delivery.

agentmail lists delete \
  --direction receive \
  --type block \
  --entry noise@example.com

Any key can read lists. Creating and deleting entries requires a verified organization.

Inspect filtered mail

Blocked inbound mail is delivered with a blocked label, not bounced or dropped. Message and thread listings exclude blocked, spam, unauthenticated, and trash by default. Pass include_blocked=true and use a key with label_blocked_read to inspect blocked mail.

• spam means the message failed the delivery spam verdict.
• unauthenticated means SPF, DKIM, and DMARC headers were all absent. Mail with present but failing authentication headers is dropped before delivery and cannot be recovered.

A blocked outbound recipient, or a recipient missing from a populated send allow list, causes 403 MessageRejectedError. The response names every blocked recipient and its reason; AgentMail sends nothing.

Handle automatic blocks

AgentMail creates organization-scope send block entries from delivery feedback:

Transient bounces create no entry. Complaint and unsubscribe entries remain read-only because the recipient asked to stop hearing from you, and programmatically re-enabling sends would damage your sender reputation. Deleting either returns 409 CannotDeleteError.

Unblock a recipient

To send to an address after resolving a permanent bounce, delete its organization send block entry:

agentmail lists delete \
  --direction send \
  --type block \
  --entry user@example.com

For custom-domain sends, deleting the entry clears the block. Shared agentmail.to sends also use an Amazon SES account-level suppression list, populated by bounce and complaint feedback and unsubscribe clicks. Deleting the AgentMail entry does not clear that suppression.