← Back to docs
Stats API
Stats API
Retrieve aggregated, daily, hourly, and per-ISP sending statistics for your domains.
Monitor your deliverability
Use the Stats API to track delivery rates, bounce rates, and complaint rates over time. Monitoring these metrics helps you catch deliverability issues early, maintain a healthy sender reputation, and optimize your email sending strategy.
Get Aggregated Stats
GET /v1/domains/:id/stats
Returns aggregated sending metrics for a domain over a configurable number of days. Includes calculated rates (delivery, bounce, open, click, complaint) and current-day/hour volume.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
days | integer | Number of days to aggregate (default: 7, max: 90) |
Example Request
curl -X GET "https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851/stats?days=30" \
-H "Authorization: Bearer ps_live_your_api_key"
Response
{
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"domain": "yourapp.com",
"period_days": 30,
"metrics": {
"period_days": 30,
"total_sent": 15420,
"total_delivered": 15105,
"total_bounced": 280,
"total_hard_bounce": 45,
"total_complaints": 3,
"total_opened": 6042,
"total_clicked": 1812,
"delivery_rate": 0.9796,
"bounce_rate": 0.0182,
"hard_bounce_rate": 0.0029,
"complaint_rate": 0.0002,
"open_rate": 0.4000,
"click_rate": 0.1200
},
"today_sent": 512,
"this_hour_sent": 34
}
Get Daily Stats
GET /v1/domains/:id/stats/daily
Returns daily aggregated statistics for a domain. Each entry represents one day and includes absolute counts and calculated rates.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
days | integer | Number of days to retrieve (default: 30, max: 90) |
Example Request
curl -X GET "https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851/stats/daily?days=7" \
-H "Authorization: Bearer ps_live_your_api_key"
Response
{
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"domain": "yourapp.com",
"days": 7,
"stats": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"date": "2026-02-10T00:00:00Z",
"emails_sent": 2150,
"emails_delivered": 2108,
"emails_bounced": 38,
"hard_bounces": 5,
"soft_bounces": 33,
"complaints": 0,
"emails_opened": 842,
"emails_clicked": 253,
"delivery_rate": 0.9805,
"bounce_rate": 0.0177,
"hard_bounce_rate": 0.0023,
"complaint_rate": 0.0,
"open_rate": 0.3994,
"created_at": "2026-02-10T00:05:00Z"
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"date": "2026-02-09T00:00:00Z",
"emails_sent": 1980,
"emails_delivered": 1941,
"emails_bounced": 35,
"hard_bounces": 8,
"soft_bounces": 27,
"complaints": 1,
"emails_opened": 776,
"emails_clicked": 210,
"delivery_rate": 0.9803,
"bounce_rate": 0.0177,
"hard_bounce_rate": 0.0040,
"complaint_rate": 0.0005,
"open_rate": 0.3998,
"created_at": "2026-02-09T00:05:00Z"
}
]
}
Get Hourly Stats
GET /v1/domains/:id/stats/hourly
Returns hourly sending statistics for a domain. Each entry represents one hour bucket and includes per-hour counts. Useful for identifying sending patterns and diagnosing short-term delivery issues.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
hours | integer | Number of hours to retrieve (default: 24, max: 168) |
Example Request
curl -X GET "https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851/stats/hourly?hours=48" \
-H "Authorization: Bearer ps_live_your_api_key"
Response
{
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"domain": "yourapp.com",
"hours": 48,
"from": "2026-02-08T10:00:00Z",
"to": "2026-02-10T10:00:00Z",
"stats": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"hour_bucket": "2026-02-10T09:00:00Z",
"emails_sent": 89,
"emails_delivered": 87,
"emails_bounced": 2,
"emails_deferred": 0,
"hard_bounces": 0,
"soft_bounces": 2,
"emails_opened": 31,
"emails_clicked": 8,
"complaints": 0,
"created_at": "2026-02-10T09:00:00Z",
"updated_at": "2026-02-10T09:58:12Z"
},
{
"id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"hour_bucket": "2026-02-10T08:00:00Z",
"emails_sent": 124,
"emails_delivered": 121,
"emails_bounced": 3,
"emails_deferred": 1,
"hard_bounces": 1,
"soft_bounces": 2,
"emails_opened": 45,
"emails_clicked": 12,
"complaints": 0,
"created_at": "2026-02-10T08:00:00Z",
"updated_at": "2026-02-10T08:59:45Z"
}
]
}
Get ISP Stats
GET /v1/domains/:id/stats/isp
Returns per-ISP sending statistics for a domain. Breaks down sending volume and engagement by inbox provider (Gmail, Microsoft, Yahoo, Apple, Proton, and others). Useful for identifying ISP-specific deliverability problems.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
days | integer | Number of days to aggregate (default: 7, max: 90) |
Example Request
curl -X GET "https://api.postscale.io/v1/domains/d290f1ee-6c54-4b01-90e6-d701748f0851/stats/isp?days=14" \
-H "Authorization: Bearer ps_live_your_api_key"
Response
{
"domain_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"domain": "yourapp.com",
"days": 14,
"isp_stats": [
{
"isp": "gmail",
"sent": 5230,
"delivered": 5122,
"bounced": 95,
"opened": 2048,
"clicked": 614
},
{
"isp": "microsoft",
"sent": 3840,
"delivered": 3762,
"bounced": 71,
"opened": 1152,
"clicked": 346
},
{
"isp": "yahoo",
"sent": 2100,
"delivered": 2058,
"bounced": 38,
"opened": 630,
"clicked": 189
},
{
"isp": "apple",
"sent": 980,
"delivered": 960,
"bounced": 18,
"opened": 392,
"clicked": 118
},
{
"isp": "proton",
"sent": 310,
"delivered": 304,
"bounced": 5,
"opened": 0,
"clicked": 0
},
{
"isp": "other",
"sent": 2960,
"delivered": 2899,
"bounced": 53,
"opened": 1820,
"clicked": 545
}
],
"known_isps": ["gmail", "microsoft", "yahoo", "apple", "proton"]
}
Metrics Reference
Aggregated Metrics Fields
| Field | Type | Description |
|---|---|---|
total_sent | integer | Total emails sent in the period |
total_delivered | integer | Total emails delivered |
total_bounced | integer | Total emails bounced (hard + soft) |
total_hard_bounce | integer | Total hard bounces |
total_complaints | integer | Total spam complaints |
total_opened | integer | Total unique opens |
total_clicked | integer | Total unique clicks |
delivery_rate | float | Delivered / sent (0.0 to 1.0) |
bounce_rate | float | Bounced / sent (0.0 to 1.0) |
hard_bounce_rate | float | Hard bounces / sent (0.0 to 1.0) |
complaint_rate | float | Complaints / sent (0.0 to 1.0) |
open_rate | float | Opened / delivered (0.0 to 1.0) |
click_rate | float | Clicked / delivered (0.0 to 1.0) |
Daily Stats Fields
| Field | Type | Description |
|---|---|---|
date | string | Date for this bucket (ISO 8601) |
emails_sent | integer | Emails sent on this day |
emails_delivered | integer | Emails delivered on this day |
emails_bounced | integer | Emails bounced on this day |
hard_bounces | integer | Hard bounces on this day |
soft_bounces | integer | Soft bounces on this day |
complaints | integer | Spam complaints on this day |
emails_opened | integer | Opens on this day |
emails_clicked | integer | Clicks on this day |
delivery_rate | float | Delivered / sent for this day |
bounce_rate | float | Bounced / sent for this day |
hard_bounce_rate | float | Hard bounces / sent for this day |
complaint_rate | float | Complaints / sent for this day |
open_rate | float | Opened / delivered for this day |
Hourly Stats Fields
| Field | Type | Description |
|---|---|---|
hour_bucket | string | Hour bucket timestamp (ISO 8601, truncated to hour) |
emails_sent | integer | Emails sent in this hour |
emails_delivered | integer | Emails delivered in this hour |
emails_bounced | integer | Emails bounced in this hour |
emails_deferred | integer | Emails deferred in this hour |
hard_bounces | integer | Hard bounces in this hour |
soft_bounces | integer | Soft bounces in this hour |
emails_opened | integer | Opens in this hour |
emails_clicked | integer | Clicks in this hour |
complaints | integer | Spam complaints in this hour |
ISP Stats Fields
| Field | Type | Description |
|---|---|---|
isp | string | ISP identifier (gmail, microsoft, yahoo, apple, proton, other) |
sent | integer | Emails sent to this ISP |
delivered | integer | Emails delivered to this ISP |
bounced | integer | Emails bounced at this ISP |
opened | integer | Opens at this ISP |
clicked | integer | Clicks at this ISP |