Inboxes

What is an Inbox?

People are used to the traditional Gmail limitations — only having one inbox. Thats of the past.

An Inbox is now a fully loaded, programmatically accessible API resource re-designed for the scale of AI Agents.

Think of it as being similar to a Gmail or Outlook account, but built API-first. Each Inbox has a unique email address and serves as the primary resource your agent uses to send and receive emails, giving it a first-class identity on the internet.

Unlike traditional email providers that are designed for human scale, AgentMail Inboxes are built to scale horizontally. You can create tens, hundreds, or even thousands of Inboxes for your agents on demand.

The AgentMail Hierarchy

As the diagram below illustrates, your organization is the top-level container that holds all your resources. You can provision many Inboxes within your organization, each with its own Threads, Messages, and Attachments, allowing you to manage a large fleet of agents seamlessly.

Core Capabilities

Here at AgentMail we’ve now made an Inbox is an API resource, meaning you can perform standard CRUD operations on it. Here are the core capabilities you’ll use to manage your Inboxes.

1
from agentmail import AgentMail
2
3
# Initialize the client
4
client = AgentMail(api_key="YOUR_API_KEY")
5
6
# --- Create an Inbox ---
7
# Creates a new inbox with a default agentmail.to domain
8
new_inbox = client.inboxes.create()
9
print(f"Created Inbox: {new_inbox.inbox_id}")
10
11
# --- Retrieve an Inbox ---
12
# Gets a specific inbox by its ID
13
retrieved_inbox = client.inboxes.get(inbox_id = 'my_name@domain.com')
14
print(f"Retrieved Inbox: {retrieved_inbox.inbox_id}")
15
16
# --- List Inboxes ---
17
# Lists all inboxes in your organization
18
all_inboxes = client.inboxes.list()
19
print(f"Total Inboxes: {len(all_inboxes)}")