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
20
print(f"Total Inboxes: {all_inboxes.count}")

1
# Attach metadata when creating an inbox; values may be a string, int, float, or boolean
2
inbox = client.inboxes.create(
3
    username="support-agent",
4
    metadata={
5
        "tenant_id": "acme",       # string
6
        "seat_count": 5,           # int
7
        "monthly_spend": 19.99,    # float
8
        "active": True,            # boolean
9
    },
10
)
11
12
# Read it back from any inbox response
13
print(inbox.metadata)

1
# Add or overwrite keys; the keys you omit stay unchanged
2
client.inboxes.update(
3
    inbox_id="support-agent@agentmail.to",
4
    metadata={"tier": "enterprise"},
5
)
6
7
# Remove a single key
8
client.inboxes.update(
9
    inbox_id="support-agent@agentmail.to",
10
    metadata={"tier": None},
11
)
12
13
# Clear all metadata
14
client.inboxes.update(
15
    inbox_id="support-agent@agentmail.to",
16
    metadata=None,
17
)

1
# Create a key scoped to one inbox
2
key = client.inboxes.api_keys.create(
3
    new_inbox.inbox_id,
4
    name="support-agent-key"
5
)
6
7
# The full key is only returned once
8
print(key.api_key)

1
"""
2
AgentMail Inboxes — copy into Cursor/Claude.
3
4
Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
5
6
API reference:
7
- inboxes.create(username?, domain?, display_name?, client_id?, metadata?) — client_id for idempotent retries; metadata is custom key-value data
8
- inboxes.get(inbox_id)
9
- inboxes.list(limit?, page_token?)
10
- inboxes.update(inbox_id, display_name?, metadata?) — at least one field required; metadata is merged, not replaced
11
- inboxes.delete(inbox_id)
12
- inboxes.api_keys.create(inbox_id, name) — inbox-scoped key
13
- inboxes.api_keys.list(inbox_id)
14
- inboxes.api_keys.delete(inbox_id, api_key_id)
15
16
Errors: SDK raises on 4xx/5xx. Rate limit: 429 with Retry-After.
17
"""
18
import os
19
from dotenv import load_dotenv
20
from agentmail import AgentMail
21
22
load_dotenv()
23
client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
24
25
# Create (client_id for idempotent retries)
26
inbox = client.inboxes.create(client_id="my-inbox-v1")
27
28
# Get, list
29
retrieved = client.inboxes.get(inbox.inbox_id)
30
all_inboxes = client.inboxes.list(limit=20)
31
print(f"Total: {all_inboxes.count}")