AgentMail Changelog

Summary

Inboxes now support custom metadata: your own key-value data attached to any inbox. Link an inbox to records in your own system, such as a tenant ID, user ID, or feature flags, and read it back on every inbox response. Build agents that carry your application’s context wherever an inbox goes.

What’s new?

New features:

• Inbox metadata: Attach custom key-value pairs to an inbox. Values may be a string, number, or boolean, with up to 256 keys per inbox.

Changes:

• The Inbox object now includes an optional metadata field, returned on get, list, and create responses.
• POST /v0/inboxes accepts a metadata field to set metadata at creation time.
• PATCH /v0/inboxes/:inbox_id accepts a metadata field. Updates merge into existing metadata: keys you include are added or overwritten, and keys you omit are preserved. Send a key with a null value to remove it, or set metadata to null to clear everything. Each update must include at least one of display_name or metadata.

Use cases

Build agents that:

• Tag each inbox with a tenant or customer ID so you can map inboxes back to your own data model
• Store per-inbox feature flags or routing hints that your agent reads at runtime
• Track lifecycle state, such as an onboarding step or campaign name, directly on the inbox
• Filter and organize a large fleet of inboxes by the attributes that matter to your application

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# attach metadata when creating an inbox
6
inbox = client.inboxes.create(
7
    username="support-agent",
8
    metadata={"tenant_id": "acme", "tier": "pro", "active": True},
9
)
10
11
# merge in a change; omitted keys are preserved
12
client.inboxes.update(
13
    inbox_id=inbox.inbox_id,
14
    metadata={"tier": "enterprise"},
15
)

Summary

Inbox-scoped API keys let you generate credentials that are restricted to a single inbox. This gives agents and integrations the minimum access they need, reducing the blast radius if a key is compromised.

What’s new?

New endpoints:

• GET /v0/inboxes/:inbox_id/api-keys - List all API keys scoped to an inbox
• POST /v0/inboxes/:inbox_id/api-keys - Create an API key scoped to an inbox
• DELETE /v0/inboxes/:inbox_id/api-keys/:api_key - Delete an inbox-scoped API key

Updated types:

• ApiKey and CreateApiKeyResponse now include an optional inbox_id field when the key is scoped to an inbox

Use cases

Build agents that:

• Operate with least-privilege access to a single inbox rather than an entire pod or organization
• Issue short-lived, narrowly scoped keys to third-party integrations that only need access to one address
• Rotate credentials per inbox without affecting other inboxes or pods

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# create an api key scoped to a single inbox
6
key = client.inboxes.api_keys.create(
7
    inbox_id="user@example.com",
8
    name="integration-key"
9
)
10
11
print(key.api_key)

Summary

Webhooks & Events – receive email and domain events via HTTP callbacks. Subscribe to message lifecycle events (received, sent, delivered, bounced, complained, rejected) and domain verification. Use Svix headers for verification and filter by inbox or pod. Perfect for agents that need reliable, async notifications without keeping a WebSocket open.

What’s new?

Webhook events:

• message.received - New inbound email
• message.sent - Outbound message sent
• message.delivered - Delivery confirmed
• message.bounced - Bounce (with type and recipients)
• message.complained - Spam complaint
• message.rejected - Rejection (e.g. validation)
• domain.verified - Domain verification succeeded

Delivery & verification:

• Svix-style headers: svix-id, svix-signature, svix-timestamp for verification
• Filter by inbox or pod (up to 10 per webhook)
• Payloads include inbox_id, thread_id, message_id, timestamps, and event-specific data

Use cases

Build agents that:

• React to new emails, bounces, and complaints via HTTP
• Sync email state to your database or queue
• Trigger workflows on domain verification
• Verify webhook signatures for security

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# in your webhook handler: verify signature and handle event
6
# (use Svix or the raw headers for verification)
7
def handle_webhook(request):
8
    event_id = request.headers.get("svix-id")
9
    signature = request.headers.get("svix-signature")
10
    payload = request.json()
11
    if payload.get("event_type") == "message.received":
12
        message = payload.get("message")
13
        # process new email
14
    elif payload.get("event_type") == "domain.verified":
15
        domain = payload.get("domain")
16
        # domain is verified

Summary

Introducing Custom Domains – add and verify your own domains for sending and receiving email. Use DNS verification (TXT, CNAME, MX), export zone files for easy DNS setup, and control feedback (bounce and complaint) delivery. Perfect for agents that need to send from your brand’s domain with full control over deliverability.

What’s new?

New endpoints:

• GET /domains - List all domains
• GET /domains/{domain_id} - Get domain details and verification records
• POST /domains - Create (add) a domain
• DELETE /domains/{domain_id} - Remove a domain
• GET /domains/{domain_id}/zone-file - Download zone file for DNS setup
• POST /domains/{domain_id}/verify - Trigger domain verification

Domain features:

• DNS verification with TXT, CNAME, and MX records
• Verification status: NOT_STARTED, PENDING, VERIFYING, VERIFIED, FAILED, INVALID
• Per-record status (MISSING, INVALID, VALID) for targeted fixes
• Zone file export for quick import at your DNS provider
• Optional feedback (bounce/complaint) delivery per domain

Use cases

Build systems where:

• Agents send from your verified custom domain
• You manage DNS in one place and sync via zone file
• Verification status drives onboarding or monitoring
• Bounce and complaint handling is configured per domain

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# create a domain
6
domain = client.domains.create(
7
    domain="mail.example.com",
8
    feedback_enabled=True
9
)
10
11
# get verification records and status
12
domain = client.domains.get(domain_id=domain.domain_id)
13
for record in domain.records:
14
    print(f"{record.type} {record.name}: {record.status}")
15
16
# trigger verification after updating DNS
17
client.domains.verify(domain_id=domain.domain_id)

Summary

Introducing the Drafts API – compose and manage email drafts before sending. Create drafts, update them over time, schedule send times, and send when ready. Perfect for agents that need to build messages incrementally, support reply threading, or queue emails for later delivery.

What’s new?

New endpoints:

• GET /drafts - List all drafts (with optional filters)
• GET /drafts/{draft_id} - Get a draft
• POST /inboxes/{inbox_id}/drafts - Create a draft in an inbox
• PATCH /inboxes/{inbox_id}/drafts/{draft_id} - Update a draft
• POST /inboxes/{inbox_id}/drafts/{draft_id}/send - Send a draft
• DELETE /inboxes/{inbox_id}/drafts/{draft_id} - Delete a draft

Draft features:

• Compose with to, cc, bcc, subject, plain text, and HTML body
• Reply threading via in_reply_to and references
• Schedule send with send_at for delayed delivery
• Attachments and labels
• List and filter drafts by inbox, labels, or time range

Use cases

Build agents that:

• Compose multi-step replies before sending
• Schedule follow-up emails for optimal delivery
• Queue outbound messages and send in batches
• Edit drafts based on new context or user feedback
• Maintain proper email threads with in_reply_to

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# create a draft in an inbox
6
draft = client.inboxes.drafts.create(
7
    inbox_id="support@example.com",
8
    to=["user@example.com"],
9
    subject="Re: Your request",
10
    text="We're looking into it.",
11
    in_reply_to="<message-id@example.com>"
12
)
13
14
# update the draft
15
client.inboxes.drafts.update(
16
    inbox_id="support@example.com",
17
    draft_id=draft.draft_id,
18
    text="We've resolved your request."
19
)
20
21
# send the draft
22
client.inboxes.drafts.send(
23
    inbox_id="support@example.com",
24
    draft_id=draft.draft_id
25
)

Summary

We’re excited to introduce Metrics Endpoints - two new powerful endpoints that give you deep insights into your email deliverability and agent performance. Track critical events like bounces, deliveries, rejections, and complaints with detailed timestamps to build smarter, self-optimizing email agents.

What’s new?

New endpoints:

• GET /metrics - Get comprehensive metrics across all your inboxes
• GET /inboxes/{inbox_id}/metrics - Get metrics for a specific inbox

Metrics tracked:

• Delivery events: sent, delivered, bounced, rejected
• Error tracking: complaints, spam reports
• Time-series data with detailed timestamps

Use cases

Build agents that:

• Monitor their own bounce rates in real-time
• Optimize send timing based on historical performance
• Automatically adjust behavior based on deliverability metrics
• Pause campaigns when performance drops below thresholds
• Implement intelligent retry strategies for better inbox placement

Summary

Introducing WebSocket Streaming - receive email events in real-time as they happen. Build reactive agents that respond instantly to new messages, deliveries, and bounces without polling. Perfect for building interactive, event-driven email experiences.

What’s new?

WebSocket endpoint:

• wss://ws.agentmail.to/v0 - Real-time event streaming

Events streamed:

• message.received - New inbound email detected
• message.sent - Outbound email sent successfully
• message.delivered - Delivery confirmed by recipient server
• message.bounced - Bounce detected (permanent or temporary)
• message.complained - Spam complaint received

Connection features:

• JWT-based authentication for secure connections
• Automatic reconnection with exponential backoff
• Event filtering by inbox for targeted subscriptions
• Low-latency delivery (typically under 100ms)
• Support for thousands of concurrent connections

Use cases

Build agents that:

• Respond to emails within seconds of receipt
• Monitor deliverability in real-time across all inboxes
• Trigger workflows instantly on specific events
• Build interactive conversational email experiences
• Scale to handle high-volume email operations
• React to bounces and complaints immediately

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# subscribe to events for an inbox
6
async with client.websockets.subscribe(
7
    inbox_id="support@example.com"
8
) as ws:
9
    async for event in ws:
10
        if event.type == "message.received":
11
            print(f"New email from: {event.data.from_}")
12
            response = await generate_response(event.data.text)
13
            await client.messages.reply(
14
                message_id=event.data.message_id,
15
                text=response
16
            )

Summary

Introducing Pods - team collaboration spaces for AgentMail. Share inboxes, domains, and resources across your organization while maintaining granular control. Perfect for teams building multi-agent email systems that need organized resource management.

What’s new?

New endpoints:

• POST /pods - Create a new pod (team workspace)
• GET /pods - List all pods in your organization
• GET /pods/{pod_id} - Get pod details
• DELETE /pods/{pod_id} - Delete a pod
• POST /pods/{pod_id}/inboxes - Create inbox within a pod
• POST /pods/{pod_id}/domains - Add custom domain to a pod
• GET /pods/{pod_id}/threads - List threads within a pod
• GET /pods/{pod_id}/metrics - Get metrics for a pod

Pod features:

• Shared inbox access across team members
• Per-pod domain configuration
• Isolated metrics and analytics per pod
• Organized resource hierarchy

Use cases

Build systems where:

• Multiple agents share email infrastructure
• Different teams manage their own inboxes independently
• Resources are organized by department or project
• Analytics are tracked per team workspace
• Billing and usage can be attributed to specific teams

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# create a pod for your sales team
6
pod = client.pods.create(
7
    name="Sales Team",
8
    description="Shared resources for sales agents"
9
)
10
11
# create an inbox in the pod
12
inbox = client.pods.inboxes.create(
13
    pod_id=pod.pod_id,
14
    inbox_id="sales@example.com"
15
)
16
17
# list all pods
18
pods = client.pods.list()
19
for pod in pods.pods:
20
    print(f"Pod: {pod.name} ({len(pod.inbox_ids)} inboxes)")