AgentMail Changelog

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)")