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 four list types based on two dimensions, direction (send or receive) 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")

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

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
• Any agent that needs protection from spam, phishing, or abuse

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