import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.metrics.get();
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.get_metrics()
print(result)

curl 'https://api.mails.ai/v1/metrics' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails metrics --from 2026-10-01 --to 2026-10-08 \
  --interval day

{ "name": "mails_metrics_get", "arguments": {} }

{
  "interval": "day",
  "from": "2026-10-04T12:00:00.000Z",
  "to": "2026-10-04T12:00:00.000Z",
  "agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "test_mode": false,
  "data": [
    {
      "start": "2026-10-04T12:00:00.000Z",
      "sent": 0,
      "delivered": 0,
      "bounced": 0,
      "complained": 0,
      "received": 0,
      "replies": 0
    }
  ],
  "totals": {
    "sent": 0,
    "delivered": 0,
    "bounced": 0,
    "complained": 0,
    "received": 0,
    "replies": 0
  }
}

200  Buckets for the range, oldest first.
400  Invalid request — malformed JSON or a field failed
     validation. Also feature_not_enabled when this
     server has a feature switched off (custom domains
     before they are available).
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
500  Internal server error.

Mail metrics

Counts of sent, delivered, bounced, complained, received and reply messages per day or hour (UTC).

GET/v1/metricsscope · read

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.metrics.get();
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.get_metrics()
print(result)

curl 'https://api.mails.ai/v1/metrics' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails metrics --from 2026-10-01 --to 2026-10-08 \
  --interval day

{ "name": "mails_metrics_get", "arguments": {} }

{
  "interval": "day",
  "from": "2026-10-04T12:00:00.000Z",
  "to": "2026-10-04T12:00:00.000Z",
  "agent_id": "agt_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "test_mode": false,
  "data": [
    {
      "start": "2026-10-04T12:00:00.000Z",
      "sent": 0,
      "delivered": 0,
      "bounced": 0,
      "complained": 0,
      "received": 0,
      "replies": 0
    }
  ],
  "totals": {
    "sent": 0,
    "delivered": 0,
    "bounced": 0,
    "complained": 0,
    "received": 0,
    "replies": 0
  }
}

200  Buckets for the range, oldest first.
400  Invalid request — malformed JSON or a field failed
     validation. Also feature_not_enabled when this
     server has a feature switched off (custom domains
     before they are available).
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
409  Conflict — duplicate resource, an in-progress
     idempotent request, a draft or scheduled message
     that started sending while it was being changed, or
     a thread deleted for good while one of its messages
     is being sent (duplicate_resource); or an agent
     name more than one agent has (agent_name_conflict:
     use the agent's id); or a status change on an
     archived agent, since archiving cannot be undone
     (agent_archived).
500  Internal server error.

Query Parameters

fromstring

Start of the range (ISO 8601, or YYYY-MM-DD).

tostring

End of the range, exclusive (ISO 8601, or YYYY-MM-DD).

agent_idstring

Filter by agent id or name. A key tied to one agent always reads that agent's mail, and naming another agent is a 403.

intervalstring

Bucket size.

One of: day, hour

Default: "day"

Defaults to the last 30 days by day, or the last 48 hours by hour; at most 366 days or 744 hours per call. A test key counts test mail only and a live key live mail only.

Response

intervalstring

Bucket size, in UTC: day or hour, as requested; day when the request names none.

One of: day, hour

fromstring

Start of the range, inclusive: the requested from moved back to the start of its UTC day or hour. Left out, 30 days before to by day or 48 hours by hour, rounded the same way.

tostring

End of the range, exclusive, as requested and not rounded, so the last bucket can be partial. Left out, the time of the request.

agent_idstring

The agent the counts are limited to, as its id even when the request gave its name. Absent when they cover every agent; a key tied to one agent always gets its own.

test_modeboolean

A test key counts test mail only; a live key, live mail only.

dataobject[]

Every bucket in the range, oldest first, zeros included.

Show propertiesHide properties

startstring

Start of the bucket (UTC).

sentinteger

Messages sent in this bucket, one per message whatever its recipient count. A scheduled message counts when it goes out; a send the mail provider refused does not.

deliveredinteger

Messages confirmed delivered in this bucket, counted by delivery time, not send time. Always 0 for a test key: test sends are never transmitted.

bouncedinteger

Messages that bounced in this bucket, counted by bounce time. A soft bounce, which marks a message delayed, is not counted; always 0 for a test key.

complainedinteger

Messages a recipient reported as spam in this bucket, counted by complaint time. Always 0 for a test key.

receivedinteger

Messages received in this bucket, counted by arrival time. Quarantined mail and mail received over a limit count too.

repliesinteger

Received messages that answered a thread.

totalsobject

Each count summed over every bucket in the range.

Show propertiesHide properties

sentinteger

Messages sent in the range, counted by send time.

deliveredinteger

Messages confirmed delivered in the range, counted by delivery time.

bouncedinteger

Messages that bounced in the range, counted by bounce time.

complainedinteger

Messages reported as spam in the range, counted by complaint time.

receivedinteger

Messages received in the range, counted by arrival time.

repliesinteger

Received messages in the range that answered a thread.

Was this page helpful?