Metrics

The Metrics API provides engagement analytics across your organisation. Query aggregate statistics like sends, deliveries, opens, clicks, bounces, and complaints over configurable time periods.

Tenant-wide metrics

GET /api/metrics

Returns aggregate metrics for your entire organisation, either monthly (default) or daily. Counters are returned as a single metrics object — there is no totals/timeseries split.

Query parameters

Parameter	Type	Required	Description
`period`	string	No	`daily` or `monthly`. Defaults to `monthly`.
`yearMonth`	string	No	For `monthly`: the month as `YYYY-MM`. Defaults to the current month.
`date`	string	No	For `daily`: a single day as `YYYY-MM-DD`. Defaults to today.
`startDate`	string	No	For `daily`: start of a date range (`YYYY-MM-DD`). Use with `endDate`.
`endDate`	string	No	For `daily`: end of a date range (`YYYY-MM-DD`).

Response

Monthly (or single-day) requests return the period key plus a metrics object:

{
  "period": "monthly",
  "yearMonth": "2025-09",
  "metrics": {
    "scheduled": 12800,
    "sent": 12500,
    "cancelled": 60,
    "delivered": 12100,
    "bounced": 350,
    "bouncedHard": 210,
    "bouncedSoft": 140,
    "complained": 50,
    "opened": 4800,
    "clicked": 1200,
    "replied": 90,
    "updatedAt": "2025-09-30T23:59:59.999Z"
  }
}

A daily range request (period=daily with startDate and endDate) instead returns startDate, endDate, and a metrics array with one entry per day.

Examples

# Current month (default)
curl "https://api.kraiter.com/api/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY"

# A specific month
curl "https://api.kraiter.com/api/metrics?yearMonth=2025-09" \
  -H "Authorization: Bearer YOUR_API_KEY"

# A daily range
curl "https://api.kraiter.com/api/metrics?period=daily&startDate=2025-09-01&endDate=2025-09-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

const metrics = await kraiter.metrics.get({ yearMonth: "2025-09" });

console.log(metrics.metrics.delivered); // 12100

Sequence metrics

GET /api/metrics/sequences/:id

Returns monthly metrics for a specific sequence.

Path parameters

Parameter	Type	Description
`id`	string	The sequence ID.

Query parameters

Parameter	Type	Required	Description
`yearMonth`	string	No	The month as `YYYY-MM`. Defaults to the current month.

Response

Returns sequenceId, yearMonth, and a metrics object with the same counters as tenant-wide metrics.

{
  "sequenceId": "onboarding",
  "yearMonth": "2025-09",
  "metrics": {
    "scheduled": 1200,
    "sent": 1180,
    "delivered": 1150,
    "opened": 640,
    "clicked": 210,
    "bounced": 20,
    "complained": 3,
    "updatedAt": "2025-09-30T23:59:59.999Z"
  }
}

Errors

Code	Description
`SEQUENCE_NOT_FOUND`	No sequence with this ID exists.

Examples

curl "https://api.kraiter.com/api/metrics/sequences/onboarding?yearMonth=2025-09" \
  -H "Authorization: Bearer YOUR_API_KEY"

const metrics = await kraiter.metrics.sequence("onboarding", {
  yearMonth: "2025-09",
});

To list every sequence's metrics for a month at once, use GET /api/metrics/sequences (returns an items array with a yearMonth and optional nextCursor).

Template metrics

GET /api/metrics/templates/:id

Returns monthly metrics for a specific template across all sends (both transactional and sequence-based).

Path parameters

Parameter	Type	Description
`id`	string	The template ID.

Query parameters

Parameter	Type	Required	Description
`yearMonth`	string	No	The month as `YYYY-MM`. Defaults to the current month.

Response

Returns templateId, yearMonth, and a metrics object with the same counters as tenant-wide metrics.

Errors

Code	Description
`TEMPLATE_NOT_FOUND`	No template with this ID exists.

Examples

curl "https://api.kraiter.com/api/metrics/templates/welcome-email?yearMonth=2025-06" \
  -H "Authorization: Bearer YOUR_API_KEY"

const metrics = await kraiter.metrics.template("welcome-email", {
  yearMonth: "2025-06",
});

To list every template's metrics for a month at once, use GET /api/metrics/templates (returns an items array with a yearMonth and optional nextCursor).

Metric fields

Every metrics object includes these counters:

Field	Description
`scheduled`	Sends scheduled during the period.
`sent`	Total emails sent (handed off to SES).
`cancelled`	Scheduled sends cancelled by a gate before sending.
`delivered`	Emails confirmed delivered to the recipient's mail server.
`bounced`	Hard and soft bounces combined.
`bouncedHard`	Permanent (hard) bounces.
`bouncedSoft`	Temporary (soft) bounces.
`complained`	Spam complaints received via feedback loops.
`opened`	Opens (tracked via pixel).
`clicked`	Clicks on tracked links.
`replied`	Replies received.
`updatedAt`	When the metrics were last updated (ISO 8601).

Derived rates

The API returns raw counts. To calculate rates, divide by the relevant base:

Rate	Formula
Delivery rate	`delivered / sent`
Open rate	`opened / delivered`
Click rate	`clicked / delivered`
Bounce rate	`bounced / sent`
Complaint rate	`complained / delivered`

Aggregation periods

Tenant-wide metrics support two periods; sequence and template metrics are monthly only.

Period	Description
`monthly`	One aggregated `metrics` object for a calendar month (`yearMonth`). The default.
`daily`	A single day (`date`) or, with `startDate`/`endDate`, an array of per-day `metrics`.

Metrics

On this page