AgentMail Changelog

Summary

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

What’s new?

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:

• Usage series: Each point is the running total of a usage type at that timestamp, not the change within the bucket. An idle scope renders a flat line at its current level, so charts stay meaningful even with no activity in the window.
• Usage types: 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.
• Bucketing: 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().
• Metric queries now clamp a future end to the current time instead of returning phantom future points, and period/limit must be whole numbers.
• The documented metric event types now match what the API accepts: added message.received.spam, message.received.blocked, message.received.unauthenticated, and domain.verified; removed message.delayed, which the API never accepted.

Use cases

Build agents that:

• Chart storage growth over time and archive old threads before hitting quota
• Monitor message and thread volume per inbox to spot runaway automations
• Verify cleanup actually happened by watching usage drop after bulk deletes
• Compare pods by inbox and domain footprint to balance workloads

1
from agentmail import AgentMail
2
3
client = AgentMail(api_key="your-api-key")
4
5
# storage growth for the last week, one point per hour
6
usage = client.metrics.query_usage(
7
    usage_types=["storage_bytes"],
8
    start="2026-06-05T00:00:00Z",
9
    period=3600,
10
)
11
12
for point in usage["storage_bytes"]:
13
    print(point.timestamp, point.value)
14
15
# usage for a single inbox (storage, messages, threads)
16
inbox_usage = client.inboxes.metrics.query_usage(inbox_id="support@agentmail.to")
17
18
# event counts now live at /metrics/events
19
events = client.metrics.query_events(
20
    event_types=["message.sent", "message.bounced"],
21
    period=3600,
22
)