Latest API and SDK updates. Subscribe via RSS · Discord
You can now track cumulative usage over time. The new usage endpoint returns running totals of storage, messages, threads, inboxes, domains, and pods — for your whole organization, a single pod, or a single inbox. Event counts also move to a dedicated /metrics/events path, so the metrics API now cleanly separates “what happened” (events) from “what you have” (usage).
New endpoints:
GET /v0/metrics/usage - Cumulative usage series for the organization.GET /v0/pods/:pod_id/metrics/usage - Cumulative usage series for a pod.GET /v0/inboxes/:inbox_id/metrics/usage - Cumulative usage series for an inbox.GET /v0/metrics/events (and pod/inbox variants) - The canonical path for event counts, replacing bare GET /v0/metrics.New features:
storage_bytes, message_count, thread_count, inbox_count, domain_count, and pod_count. Filter with the usage_types query parameter, or omit it to get every type the scope carries. Inboxes carry the first three; pods add inbox_count and domain_count; organizations add pod_count.period sets the bucket size in seconds. The range divided by period must not exceed 1000 buckets — narrow the range or coarsen the period for fine-grained series.Changes:
GET /v0/metrics (and its pod/inbox variants) is replaced by /metrics/events. The old path still responds, so existing clients keep working, but it’s removed from the docs and SDKs — use client.metrics.queryEvents() in place of client.metrics.query().end to the current time instead of returning phantom future points, and period/limit must be whole numbers.message.received.spam, message.received.blocked, message.received.unauthenticated, and domain.verified; removed message.delayed, which the API never accepted.Build agents that:
Check out the Metrics API reference for full parameter details.
You can now create inboxes on any subdomain of a verified domain without registering each subdomain separately. Enable subdomains_enabled on a domain, publish the single wildcard MX record it returns, and create inboxes on any subdomain on demand. Build agents that spin up addresses like agent@bot.example.com or support@team1.example.com the moment you need them.
New features:
subdomains_enabled. When enabled, the domain’s verification records include a wildcard MX record (*.<domain>) to publish on the top-level domain. Once it is published and verified, inboxes can be created on any subdomain of that domain.Changes:
POST /v0/domains accepts an optional subdomains_enabled flag (defaults to false).PATCH /v0/domains/:domain_id now accepts subdomains_enabled and applies partial updates: send at least one of feedback_enabled or subdomains_enabled, and omitted fields are left unchanged. Enabling subdomains on an already-verified domain returns it to pending until the new wildcard MX record is published; sending is not interrupted.subdomains_enabled field.422 error.Build agents that:
support@acme.example.com)billing., outreach., support.) without registering each oneLearn more in the Setting Up Subdomains guide.
You can now search messages and threads by keyword. Full-text search ranks results by relevance across the sender, recipients, subject, and message body, and works per-inbox or across your entire organization. List endpoints also gained substring filters, so you can narrow a list to a specific sender, recipient, or subject without paging through everything. Build agents that find the right conversation instead of scanning every thread.
New endpoints:
GET /v0/inboxes/:inbox_id/messages/search - Full-text search of messages in an inbox, ranked by relevance.GET /v0/threads/search - Org-wide full-text search across threads in every inbox.GET /v0/inboxes/:inbox_id/threads/search - Full-text search of threads in a single inbox.GET /v0/pods/:pod_id/threads/search - Full-text search of threads in a pod.New features:
q query matches against the sender, recipients, and subject (substring) and the message body (tokenized full text). Results are ordered by relevance. Spam, trash, blocked, and unauthenticated items are always excluded, and limit is capped at 100.highlights object with the matched fragments per field, with matched terms wrapped in **. A field appears only when it matched, so the present keys also tell you which fields produced the hit.Changes:
GET /v0/inboxes/:inbox_id/messages now accepts from, to, and subject substring filters. to matches the to, cc, or bcc fields.GET /v0/threads, GET /v0/inboxes/:inbox_id/threads, and GET /v0/pods/:pod_id/threads now accept senders, recipients, and subject substring filters.limit at 100; results keep the usual newest-first ordering.Build agents that:
highlightsInboxes 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.
New features:
Changes:
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.Build agents that:
Learn more about attaching and updating inbox data in the Inboxes metadata guide.
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.
New endpoints:
GET /v0/inboxes/:inbox_id/api-keys - List all API keys scoped to an inboxPOST /v0/inboxes/:inbox_id/api-keys - Create an API key scoped to an inboxDELETE /v0/inboxes/:inbox_id/api-keys/:api_key - Delete an inbox-scoped API keyUpdated types:
ApiKey and CreateApiKeyResponse now include an optional inbox_id field when the key is scoped to an inboxBuild agents that:
Learn more about API key scoping in the API Keys reference.
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.
Webhook events:
message.received - New inbound emailmessage.sent - Outbound message sentmessage.delivered - Delivery confirmedmessage.bounced - Bounce (with type and recipients)message.complained - Spam complaintmessage.rejected - Rejection (e.g. validation)domain.verified - Domain verification succeededDelivery & verification:
svix-id, svix-signature, svix-timestamp for verificationBuild agents that:
Set up and verify webhooks in our Webhooks documentation.
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.
New endpoints:
GET /domains - List all domainsGET /domains/{domain_id} - Get domain details and verification recordsPOST /domains - Create (add) a domainDELETE /domains/{domain_id} - Remove a domainGET /domains/{domain_id}/zone-file - Download zone file for DNS setupPOST /domains/{domain_id}/verify - Trigger domain verificationDomain features:
Build systems where:
Learn more in our Custom Domains and Managing Domains guides.
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.
New endpoints:
GET /drafts - List all drafts (with optional filters)GET /drafts/{draft_id} - Get a draftPOST /inboxes/{inbox_id}/drafts - Create a draft in an inboxPATCH /inboxes/{inbox_id}/drafts/{draft_id} - Update a draftPOST /inboxes/{inbox_id}/drafts/{draft_id}/send - Send a draftDELETE /inboxes/{inbox_id}/drafts/{draft_id} - Delete a draftDraft features:
in_reply_to and referencessend_at for delayed deliveryBuild agents that:
in_reply_toLearn more about composing and sending in our Drafts documentation.
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.
New endpoints:
GET /metrics - Get comprehensive metrics across all your inboxesGET /inboxes/{inbox_id}/metrics - Get metrics for a specific inboxMetrics tracked:
Build agents that:
Ready to build smarter agents? Check out our Metrics API documentation to get started.
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.
WebSocket endpoint:
wss://ws.agentmail.to/v0 - Real-time event streamingEvents streamed:
message.received - New inbound email detectedmessage.sent - Outbound email sent successfullymessage.delivered - Delivery confirmed by recipient servermessage.bounced - Bounce detected (permanent or temporary)message.complained - Spam complaint receivedConnection features:
Build agents that:
Get started with WebSocket Streaming to build real-time email agents.