Metrics API

Query time-series delivery metrics and aggregate summaries across all providers.

GET /v1/metrics

Retrieve time-series email event data, bucketed by the specified granularity.

Query Parameters

Parameter	Type	Default	Description
from	string (ISO 8601)	30 days ago	Start of the time range.
to	string (ISO 8601)	Now	End of the time range.
granularity	string	day	Bucket size: hour, day, week, or month.

Response

{
  "data": [
    {
      "timestamp": "2025-01-15 00:00:00",
      "sent": 1420,
      "delivered": 1385,
      "opened": 612,
      "clicked": 89,
      "bounced": 35,
      "complained": 2,
      "unsubscribed": 8
    },
    {
      "timestamp": "2025-01-16 00:00:00",
      "sent": 1510,
      "delivered": 1490,
      "opened": 701,
      "clicked": 102,
      "bounced": 20,
      "complained": 1,
      "unsubscribed": 5
    }
  ],
  "query": {
    "from": "2025-01-15T00:00:00Z",
    "to": "2025-01-17T00:00:00Z",
    "granularity": "day"
  }
}

Example

curl "https://api.optail.io/v1/metrics?from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&granularity=day" \
  -H "Authorization: Bearer ms_live_your_api_key"

GET /v1/metrics/breakdown

Get aggregate event counts grouped by provider, domain, or template.

Query Parameters

Parameter	Type	Default	Description
from	string (ISO 8601)	30 days ago	Start of the time range.
to	string (ISO 8601)	Now	End of the time range.
groupBy	string	provider	Grouping dimension: provider, domain, or template.

Response

{
  "data": [
    {
      "name": "SENDGRID",
      "sent": 8500,
      "delivered": 8350,
      "opened": 3200,
      "clicked": 480,
      "bounced": 150,
      "complained": 12
    },
    {
      "name": "POSTMARK",
      "sent": 3200,
      "delivered": 3180,
      "opened": 1450,
      "clicked": 210,
      "bounced": 20,
      "complained": 3
    }
  ],
  "query": {
    "from": "2025-01-01T00:00:00Z",
    "to": "2025-01-31T23:59:59Z",
    "groupBy": "provider"
  }
}

GET /v1/metrics/summary

Get a high-level summary with totals and computed rates for the given time range.

Query Parameters

Parameter	Type	Default	Description
from	string (ISO 8601)	30 days ago	Start of the time range.
to	string (ISO 8601)	Now	End of the time range.

Response

{
  "data": {
    "totalSent": 11700,
    "totalDelivered": 11530,
    "totalOpened": 4650,
    "totalClicked": 690,
    "totalBounced": 170,
    "totalComplained": 15,
    "totalUnsubscribed": 42,
    "deliveryRate": 0.9855,
    "openRate": 0.4033,
    "clickRate": 0.1484,
    "bounceRate": 0.0145,
    "complaintRate": 0.0013
  },
  "period": {
    "from": "2025-01-01T00:00:00Z",
    "to": "2025-01-31T23:59:59Z"
  }
}

Rate Calculations

Rate	Formula
deliveryRate	totalDelivered / totalSent
openRate	totalOpened / totalDelivered
clickRate	totalClicked / totalOpened
bounceRate	totalBounced / totalSent
complaintRate	totalComplained / totalDelivered

All rates are returned as decimals rounded to 4 decimal places (e.g., 0.9855 = 98.55%).

GET /v1/messages

List sent messages with filtering and pagination.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number.
limit	integer	20	Items per page (max 100).
status	string	--	Filter by status: QUEUED, SENDING, SENT, DELIVERED, BOUNCED, FAILED.
search	string	--	Search by subject line.

Response

{
  "data": [
    {
      "id": "msg-uuid",
      "providerAccountId": "pa-uuid",
      "fromAddress": "hello@yourdomain.com",
      "toHash": "sha256...",
      "subject": "Welcome!",
      "status": "DELIVERED",
      "tags": ["welcome"],
      "providerMessageId": "provider-id",
      "createdAt": "2025-01-15T10:00:00Z",
      "sentAt": "2025-01-15T10:00:01Z",
      "deliveredAt": "2025-01-15T10:00:03Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 142, "totalPages": 8 }
}

GET /v1/messages/:id

Get a single message with its full event history.

Response

{
  "data": {
    "id": "msg-uuid",
    "fromAddress": "hello@yourdomain.com",
    "subject": "Welcome!",
    "status": "DELIVERED",
    "tags": ["welcome"],
    "events": [
      { "eventType": "QUEUED", "occurredAt": "2025-01-15T10:00:00Z" },
      { "eventType": "SENT", "occurredAt": "2025-01-15T10:00:01Z" },
      { "eventType": "DELIVERED", "occurredAt": "2025-01-15T10:00:03Z" },
      { "eventType": "OPENED", "occurredAt": "2025-01-15T10:05:12Z" }
    ]
  }
}