Lists

Fresh 🌱

Learn how to use Lists to control which email addresses and domains your agents can send to or receive from.

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.

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

const entries = await client.lists.list("receive", "allow", { limit: 10 });

# list entries from the receive allowlist
agentmail lists list \
  --direction receive \
  --type allow \
  --limit 10

Create entry

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

# allow list - no reason needed
client.lists.create("receive", "allow", entry="partner@example.com")

# block list - reason optional
client.lists.create("receive", "block", entry="spam@example.com", reason="spam")

// allow list - no reason needed
await client.lists.create("receive", "allow", { entry: "partner@example.com" });

// block list - reason optional
await client.lists.create("receive", "block", { entry: "spam@example.com", reason: "spam" });

# allow list - no reason needed
agentmail lists create \
  --direction receive \
  --type allow \
  --entry partner@example.com

# block list - reason optional
agentmail lists create \
  --direction receive \
  --type block \
  --entry spam@example.com \
  --reason spam

Get entry

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

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

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

# get a specific entry
agentmail lists get \
  --direction receive \
  --type allow \
  --entry partner@example.com

Delete entry

Remove an entry from a list.

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

await client.lists.delete("receive", "allow", "partner@example.com");

# delete an entry
agentmail lists delete \
  --direction receive \
  --type allow \
  --entry partner@example.com

Inbox-scoped lists

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

# Add to an inbox-level receive allowlist
client.inboxes.lists.create(
    "inbox_id", "receive", "allow", entry="vip@example.com"
)

# List inbox-level entries
entries = client.inboxes.lists.list("inbox_id", "receive", "allow")

// Add to an inbox-level receive allowlist
await client.inboxes.lists.create("inbox_id", "receive", "allow", {
  entry: "vip@example.com",
});

// List inbox-level entries
const entries = await client.inboxes.lists.list("inbox_id", "receive", "allow");

# add to an inbox-level receive allowlist
agentmail inboxes:lists create \
  --inbox-id inbox_id \
  --direction receive \
  --type allow \
  --entry vip@example.com

# list inbox-level entries
agentmail inboxes:lists list \
  --inbox-id inbox_id \
  --direction receive \
  --type allow

Reply lists

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

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

// Only allow replies from a specific domain
await client.lists.create("reply", "allow", { entry: "nobu.com" });

# only allow replies from a specific domain
agentmail lists create \
  --direction reply \
  --type 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.

"""
AgentMail Lists, copy into Cursor/Claude.

Filter emails by allow/block for send/receive/reply. 6 types: receive|send|reply x allow|block.
Lists can be scoped to org, pod, or inbox level.

API reference (org-level):
- lists.list(direction, type, limit?, page_token?)
- lists.create(direction, type, entry, reason?), reason only for block lists
- lists.get(direction, type, entry)
- lists.delete(direction, type, entry)

Pod-level: pods.lists.list(pod_id, direction, type, ...) and same for create/get/delete.
Inbox-level: inboxes.lists.list(inbox_id, direction, type, ...) and same for create/get/delete.

Entry: full email (user@domain.com) or domain (example.com).
Cascade: inbox > pod > org (most specific scope wins).
Reply lists: inbound replies (detected via In-Reply-To) check reply lists, not receive lists.
"""
from agentmail import AgentMail

client = AgentMail(api_key="YOUR_API_KEY")

# Org-level lists
entries = client.lists.list("receive", "allow", limit=10)
client.lists.create("receive", "allow", entry="partner@example.com")
client.lists.create("receive", "block", entry="spam@example.com", reason="spam")
e = client.lists.get("receive", "allow", entry="partner@example.com")
client.lists.delete("receive", "allow", entry="partner@example.com")

# Reply lists
client.lists.create("reply", "allow", entry="nobu.com")

# Inbox-level lists
client.inboxes.lists.create("inbox_id", "receive", "allow", entry="vip@example.com")
inbox_entries = client.inboxes.lists.list("inbox_id", "receive", "allow")

/**
 * AgentMail Lists, copy into Cursor/Claude.
 *
 * Filter emails by allow/block for send/receive/reply. 6 types: receive|send|reply x allow|block.
 * Lists can be scoped to org, pod, or inbox level.
 *
 * API reference (org-level):
 * - lists.list(direction, type, { limit?, pageToken? })
 * - lists.create(direction, type, { entry, reason? }) — reason only for block
 * - lists.get(direction, type, entry)
 * - lists.delete(direction, type, entry)
 *
 * Pod-level: pods.lists.list(podId, direction, type, ...) and same for create/get/delete.
 * Inbox-level: inboxes.lists.list(inboxId, direction, type, ...) and same for create/get/delete.
 *
 * Entry: full email or domain.
 * Cascade: inbox > pod > org (most specific scope wins).
 * Reply lists: inbound replies (detected via In-Reply-To) check reply lists, not receive lists.
 */
import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });

async function main() {
  // Org-level lists
  const entries = await client.lists.list("receive", "allow", { limit: 10 });
  await client.lists.create("receive", "allow", { entry: "partner@example.com" });
  await client.lists.create("receive", "block", { entry: "spam@example.com", reason: "spam" });
  const e = await client.lists.get("receive", "allow", "partner@example.com");
  await client.lists.delete("receive", "allow", "partner@example.com");

  // Reply lists
  await client.lists.create("reply", "allow", { entry: "nobu.com" });

  // Inbox-level lists
  await client.inboxes.lists.create("inbox_id", "receive", "allow", {
    entry: "vip@example.com",
  });
  const inboxEntries = await client.inboxes.lists.list(
    "inbox_id", "receive", "allow"
  );
}
main();