How do I set up allowlists and blocklists?

Allowlists and blocklists let you control who your AI agent can communicate with. This is a critical safety feature for autonomous agents running in production with minimal human oversight.

How Lists work

AgentMail provides six list types based on two dimensions, direction (send, receive, or reply) and type (allow or block):

Each entry can be either a full email address (e.g., partner@example.com) or an entire domain (e.g., example.com).

Setting up lists via the SDK

Add an entry

1
from agentmail import AgentMail
2
3
client = AgentMail()
4
5
# Allow receiving from a specific domain
6
client.lists.create("receive", "allow", entry="trusted-corp.com")
7
8
# Block a specific sender (with optional reason)
9
client.lists.create("receive", "block", entry="spam@example.com", reason="spam")
10
11
# Restrict sending to only certain addresses
12
client.lists.create("send", "allow", entry="verified-prospect@example.com")
13
14
# Prevent sending to a domain
15
client.lists.create("send", "block", entry="competitor.com")

List entries

1
# View all entries in a list
2
entries = client.lists.list("receive", "allow")

Remove an entry

1
client.lists.delete("receive", "block", entry="spam@example.com")

Inbox-scoped lists

Lists can be applied at the inbox level for per-inbox filtering. For example, one inbox might only accept emails from meta.com, while another inbox in the same pod accepts from partner.com.

1
# This inbox only accepts emails from meta.com
2
client.inboxes.lists.create(
3
    "support@yourdomain.com", "receive", "allow", entry="meta.com"
4
)
5
6
# A different inbox accepts from partner.com
7
client.inboxes.lists.create(
8
    "sales@yourdomain.com", "receive", "allow", entry="partner.com"
9
)

Inbox-level lists override pod-level and org-level lists. If the inbox-level list has a match, pod and org lists are not checked.

Reply lists

Reply lists control filtering for inbound emails that are replies to previous outbound messages. When an inbound email arrives, AgentMail checks the In-Reply-To header:

• If the email is a reply to a previous outbound message, only the reply lists are checked. Receive lists are skipped.
• If the email is not a reply, only the receive lists are checked. Reply lists are skipped.

By default, when reply lists are empty, all replies are allowed. This is useful for agents that initiate outbound emails (such as making reservations or sending inquiries) and need to receive the responses.

1
# Block replies from a specific sender
2
client.inboxes.lists.create(
3
    "agent@yourdomain.com", "reply", "block", entry="spam-restaurant.com"
4
)

Common patterns for agents

Outreach agent: Use a send allowlist to restrict your agent to only email verified prospects. This prevents the agent from accidentally emailing the wrong people.

1
# Only allow sending to verified prospects
2
for prospect in verified_prospects:
3
    client.lists.create("send", "allow", entry=prospect.email)

Personal Agent (Openclaw, Manus, etc.): Use a receive allowlist to restrict your agent to only respond to emails from specific people or domains.

1
# Only accept emails from your own address and trusted domains
2
client.lists.create("receive", "allow", entry="you@yourcompany.com")
3
client.lists.create("receive", "allow", entry="trusted-partner.com")

Anti-spam: Use a receive blocklist to filter out known spam senders or unwanted automated emails.

1
# Block known spam domains
2
client.lists.create("receive", "block", entry="spam-domain.com", reason="spam")

Task-oriented agent (making reservations, bookings, etc.): Use a receive allowlist to restrict inbound to your organization’s domain, but leave reply lists open (default) so replies to agent-initiated outbound emails come through.

1
# Only accept unsolicited emails from your org
2
client.inboxes.lists.create(
3
    "agent@yourdomain.com", "receive", "allow", entry="yourdomain.com"
4
)
5
6
# Replies to emails the agent sends (e.g., restaurant reservations)
7
# are allowed by default, no reply list configuration needed.
8
# Optionally block specific reply senders:
9
client.inboxes.lists.create(
10
    "agent@yourdomain.com", "reply", "block", entry="spam-restaurant.com"
11
)

Why this matters for agents

Without guardrails, an autonomous agent could email the wrong people, respond to phishing attempts, or get caught in infinite email loops with another bot. Lists are your safety rails. They are especially important for:

• Production agents operating with minimal human oversight
• Outreach agents that should only contact approved recipients
• Support agents that should only respond to known customers
• Task-oriented agents that send outbound emails and need replies to come through
• Any agent that needs protection from spam, phishing, or abuse

For more details on the Lists API, see the Lists core concept documentation.