Stats

The Stats API provides aggregated metrics and counts for your emails, useful for reporting and dashboard widgets.

Base URL

https://api.unsent.dev/v1/stats

Overview

The Stats API returns absolute counts of email events (e.g., total sent, total delivered) within a specified date range. This differs from the Metrics API which focuses on rates and percentages.

Features

Email Counts

Get total counts for sent, delivered, opened, clicked, bounced, and more

Endpoints

Get Email Statistics

GET /v1/stats

Retrieve aggregated statistics for emails sent within a date range.

Query Parameters:

Parameter	Type	Required	Description
`startDate`	`string`	No	Start date for the statistics (ISO 8601)
`endDate`	`string`	No	End date for the statistics (ISO 8601)

Example Request:

curl -X GET "https://api.unsent.dev/v1/stats?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer your-api-key"

Response (200 OK):

{
  "totalSent": 5000,
  "totalDelivered": 4900,
  "totalOpened": 2500,
  "totalClicked": 800,
  "totalBounced": 50,
  "totalComplained": 10,
  "deliveryRate": 98.0,
  "openRate": 51.0,
  "clickRate": 32.0,
  "bounceRate": 1.0,
  "complaintRate": 0.2
}

Error Responses:

400 Bad Request - Invalid date format
401 Unauthorized - API key is missing or invalid
500 Internal Server Error - Server error