AgentMail pods > metrics API
The pods > metrics API from AgentMail — 2 operation(s) for pods > metrics.
The pods > metrics API from AgentMail — 2 operation(s) for pods > metrics.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/agentmail:agentmail-pods-metrics-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Reference pods > metrics API
version: 1.0.0
servers:
- url: https://api.agentmail.to
description: prod
- url: https://x402.api.agentmail.to
description: prod-x402
- url: https://mpp.api.agentmail.to
description: prod-mpp
- url: https://api.agentmail.eu
description: eu-prod
tags:
- name: pods > metrics
paths:
/v0/pods/{pod_id}/metrics/events:
get:
operationId: pods_metrics_queryEvents
summary: Query Events
description: 'Counts of email events (sent, delivered, bounced, etc.) over time for
the pod. Defaults to the last 24 hours; `start` must be within the last
90 days, and a future `end` is clamped to now. Omit `period` for
individual event counts, or set it to sum counts into buckets of that
many seconds.
**CLI:**
```bash
agentmail pods metrics query-events --pod-id
```'
tags:
- pods > metrics
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: event_types
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_MetricEventTypes'
- name: start
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Start'
- name: end
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_End'
- name: period
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Period'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_MetricLimit'
- name: descending
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Descending'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/metrics_QueryMetricsResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
security:
- Bearer: []
/v0/pods/{pod_id}/metrics/usage:
get:
operationId: pods_metrics_queryUsage
summary: Query Usage
description: 'Cumulative usage series for the pod. Each point is the running total of
the usage type at that timestamp, not the change within the bucket.
Pod-scoped queries carry every usage type except `pod_count`; requested
types that don''t apply to the scope are ignored. Defaults to the last
24 hours; `start` must be within the last 90 days, and a future `end`
is clamped to now. The range divided by `period` must not exceed 1000
buckets.'
tags:
- pods > metrics
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: usage_types
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_UsageTypes'
- name: start
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Start'
- name: end
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_End'
- name: period
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Period'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_MetricLimit'
- name: descending
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Descending'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/metrics_QueryUsageResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
security:
- Bearer: []
/v0/pods/{pod_id}/metrics/rates:
get:
operationId: pods_metrics_queryRates
summary: Query Rates
description: 'Rolling bounce and complaint rates for the pod. At each `period` grid
point, the bounced (or complained) messages over the preceding
`window` divided by the messages sent over the same window, with the
send count alongside. Account moderation evaluates the organization-wide
rate, so use the organization endpoint to see the number it acts on;
the pod view shows which pods contribute. Defaults to the rolling
24-hour rate sampled hourly over the last day; `start` must be within
the last 90 days, `window` must be a whole multiple of `period`, and
the range plus window divided by `period` must not exceed 1000
buckets.
**CLI:**
```bash
agentmail pods metrics query-rates --pod-id
```'
tags:
- pods > metrics
parameters:
- name: pod_id
in: path
required: true
schema:
$ref: '#/components/schemas/pods_PodId'
- name: rate_types
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_RateTypes'
- name: start
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Start'
- name: end
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_End'
- name: period
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_RatePeriod'
- name: window
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Window'
- name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_MetricLimit'
- name: descending
in: query
required: false
schema:
$ref: '#/components/schemas/metrics_Descending'
responses:
'200':
description: Response with status 200
content:
application/json:
schema:
$ref: '#/components/schemas/metrics_QueryRatesResponse'
'400':
description: Error response with status 400
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationErrorResponse'
security:
- Bearer: []
components:
schemas:
ErrorCode:
type: string
description: Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text.
title: ErrorCode
pods_PodId:
type: string
description: ID of pod.
title: PodId
metrics_RatePeriod:
type: integer
description: 'How often a point is sampled, as a whole number of seconds between 60
and 86400. Defaults to 3600 (one point per hour).'
title: RatePeriod
metrics_Start:
type: string
format: date-time
description: Start timestamp for the query.
title: Start
ValidationErrorResponse:
type: object
properties:
name:
$ref: '#/components/schemas/ErrorName'
code:
$ref: '#/components/schemas/ErrorCode'
message:
$ref: '#/components/schemas/ErrorMessage'
errors:
description: Validation errors. Each entry has a path and a message identifying the invalid field.
fix:
$ref: '#/components/schemas/ErrorFix'
docs:
$ref: '#/components/schemas/ErrorDocs'
required:
- name
- errors
title: ValidationErrorResponse
metrics_Window:
type: integer
description: 'How far back each point looks, as a whole number of seconds. Must be a
whole multiple of `period`, at most 30 days (2592000). Defaults to 86400
(a rolling 24-hour rate).'
title: Window
metrics_RateTypes:
type: array
items:
$ref: '#/components/schemas/metrics_RateType'
description: List of rate types to query. Omit to query both.
title: RateTypes
ErrorDocs:
type: string
description: Link to the error reference entry for this code.
title: ErrorDocs
metrics_MetricBucket:
type: object
properties:
timestamp:
type: string
format: date-time
description: Timestamp of the bucket.
count:
type: integer
description: Count of events in the bucket.
required:
- timestamp
- count
title: MetricBucket
metrics_UsagePoint:
type: object
properties:
timestamp:
type: string
format: date-time
description: Timestamp of the point.
value:
type: integer
format: int64
description: Cumulative value of the usage metric at the timestamp.
required:
- timestamp
- value
title: UsagePoint
metrics_RatePoint:
type: object
properties:
timestamp:
type: string
format: date-time
description: End of the window the point covers; the window is the `window` seconds before it.
rate:
type: number
format: double
description: 'Bounced or complained messages divided by messages sent over the
window, as a fraction (0.05 is 5%). Null when nothing was sent in
the window.'
sent:
type: integer
description: Messages sent in the window, counted per recipient.
required:
- timestamp
- sent
title: RatePoint
metrics_QueryMetricsResponse:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/metrics_MetricBucket'
description: Metrics grouped by event type.
title: QueryMetricsResponse
ErrorMessage:
type: string
description: Error message.
title: ErrorMessage
metrics_UsageType:
type: string
enum:
- storage_bytes
- message_count
- thread_count
- inbox_count
- pod_count
- domain_count
description: 'Type of usage metric. Inbox-scoped queries carry `storage_bytes`,
`message_count`, and `thread_count`; pod-scoped queries add `inbox_count`
and `domain_count`; organization-scoped queries add `pod_count`.'
title: UsageType
metrics_QueryRatesResponse:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/metrics_RatePoint'
description: Rate series grouped by rate type.
title: QueryRatesResponse
metrics_Period:
type: integer
description: Size of each time bucket as a whole number of seconds, between 1 and 86400.
title: Period
ErrorFix:
type: string
description: The concrete next action that resolves the error.
title: ErrorFix
metrics_Descending:
type: boolean
description: Sort in descending order.
title: Descending
metrics_UsageTypes:
type: array
items:
$ref: '#/components/schemas/metrics_UsageType'
description: List of usage metric types to query. Omit to query every type valid for the scope.
title: UsageTypes
metrics_QueryUsageResponse:
type: object
additionalProperties:
type: array
items:
$ref: '#/components/schemas/metrics_UsagePoint'
description: Cumulative usage series grouped by usage type.
title: QueryUsageResponse
metrics_RateType:
type: string
enum:
- bounce
- complaint
description: 'Type of rate. `bounce` is bounced messages divided by messages sent,
counting permanent and transient bounces; `complaint` is spam complaints
divided by messages sent.'
title: RateType
ErrorName:
type: string
description: Name of error.
title: ErrorName
metrics_MetricLimit:
type: integer
description: Limit on number of buckets to return.
title: MetricLimit
metrics_MetricEventType:
type: string
enum:
- message.received
- message.received.spam
- message.received.blocked
- message.received.unauthenticated
- message.sent
- message.delivered
- message.bounced
- message.complained
- message.rejected
- domain.verified
description: Type of metric event.
title: MetricEventType
metrics_MetricEventTypes:
type: array
items:
$ref: '#/components/schemas/metrics_MetricEventType'
description: List of metric event types to query.
title: MetricEventTypes
metrics_End:
type: string
format: date-time
description: End timestamp for the query.
title: End
securitySchemes:
Bearer:
type: http
scheme: bearer
x-provenance:
method: harvested
publisher: AgentMail
source: https://docs.agentmail.to/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)