Lists | AgentMail | Documentation

What are Lists?

Lists allow you to filter emails by allowing or blocking specific email addresses or domains. There are six list types based on two dimensions:

Direction: send, receive, or reply
Type: allow or block

List	Description
Receive allow	Only accept emails from these addresses or domains
Receive block	Reject emails from these addresses or domains
Send allow	Only send emails to these addresses or domains
Send block	Prevent sending emails to these addresses or domains
Reply allow	Only accept reply emails from these addresses or domains
Reply block	Reject reply emails from these addresses or domains

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

Scoping

Lists can be scoped at three levels. A narrower scope overrides a broader one:

Organization: Applies to all pods and inboxes in your org. Manage with client.lists.
Pod: Applies to all inboxes in a pod. Manage with client.pods.lists.
Inbox: Applies to a single inbox. Manage with client.inboxes.lists.

When evaluating whether to allow or block a message, AgentMail checks the most specific scope first. If an inbox-level list has a match, pod and org lists are not checked.

Reply lists

The reply direction handles inbound emails that are replies to previous outbound messages. When an inbound email arrives, AgentMail checks the In-Reply-To header to determine whether it is a reply:

If the email is a reply to a previous outbound message, only the reply lists are checked. The receive lists are skipped entirely.
If the email is not a reply, only the receive lists are checked. The reply lists are skipped entirely.

The two branches are completely separate. By default, when reply lists are empty, all replies are allowed. You can restrict replies by populating reply allow or reply block lists.

SDK examples

List entries

Retrieve entries from a list with optional pagination.

1 entries = client.lists.list("receive", "allow", limit=10)

Create entry

Add an email address or domain to a list. The reason parameter is optional and available on block lists.

1 # allow list - no reason needed
2 client.lists.create("receive", "allow", entry="partner@example.com")
3 
4 # block list - reason optional
5 client.lists.create("receive", "block", entry="spam@example.com", reason="spam")

Get entry

Retrieve a specific entry from a list by its email address or domain.

1 entry = client.lists.get("receive", "allow", entry="partner@example.com")

Delete entry

Remove an entry from a list.

1 client.lists.delete("receive", "allow", entry="partner@example.com")

Inbox-scoped lists

Manage lists for a specific inbox. The same operations are available at the inbox level.

1 # Add to an inbox-level receive allowlist
2 client.inboxes.lists.create(
3     "inbox_id", "receive", "allow", entry="vip@example.com"
4 )
5 
6 # List inbox-level entries
7 entries = client.inboxes.lists.list("inbox_id", "receive", "allow")

Reply lists

Control which addresses can send replies to an inbox’s outbound messages.

1 # Only allow replies from a specific domain
2 client.lists.create("reply", "allow", entry="nobu.com")

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for complete Lists API knowledge in one shot.

1 """
2 AgentMail Lists, copy into Cursor/Claude.
3 
4 Filter emails by allow/block for send/receive/reply. 6 types: receive|send|reply x allow|block.
5 Lists can be scoped to org, pod, or inbox level.
6 
7 API reference (org-level):
8 - lists.list(direction, type, limit?, page_token?)
9 - lists.create(direction, type, entry, reason?), reason only for block lists
10 - lists.get(direction, type, entry)
11 - lists.delete(direction, type, entry)
12 
13 Pod-level: pods.lists.list(pod_id, direction, type, ...) and same for create/get/delete.
14 Inbox-level: inboxes.lists.list(inbox_id, direction, type, ...) and same for create/get/delete.
15 
16 Entry: full email (user@domain.com) or domain (example.com).
17 Cascade: inbox > pod > org (most specific scope wins).
18 Reply lists: inbound replies (detected via In-Reply-To) check reply lists, not receive lists.
19 """
20 from agentmail import AgentMail
21 
22 client = AgentMail(api_key="YOUR_API_KEY")
23 
24 # Org-level lists
25 entries = client.lists.list("receive", "allow", limit=10)
26 client.lists.create("receive", "allow", entry="partner@example.com")
27 client.lists.create("receive", "block", entry="spam@example.com", reason="spam")
28 e = client.lists.get("receive", "allow", entry="partner@example.com")
29 client.lists.delete("receive", "allow", entry="partner@example.com")
30 
31 # Reply lists
32 client.lists.create("reply", "allow", entry="nobu.com")
33 
34 # Inbox-level lists
35 client.inboxes.lists.create("inbox_id", "receive", "allow", entry="vip@example.com")
36 inbox_entries = client.inboxes.lists.list("inbox_id", "receive", "allow")