Skip to main content
GET
Get email inbox provider metrics over time

Overview

For customers using OneSignal Email. The Email provider metrics timeseries API allows you to check email delivery, opens, clicks, bounces, failures, and spam complaints for a sending domain over time to pinpoint where deliverability problems are coming from. Metrics are bucketed by hour, day, or month. Use it to find where deliverability is slipping and act before it drags down your whole sender reputation.

How to Use this API

Use providers[] to narrow the totals to specific inbox providers (Gmail, Outlook, Yahoo, Apple, and more) and track how deliverability to them changes. Each event’s metrics are totaled across the requested providers, or across all providers when none are given. start must be before end and no more than 365 days ago, or 60 days ago for hourly granularity. events is empty when the domain is not found for the app or is not currently active for sending.

Headers

Authorization
string
default:Key YOUR_APP_API_KEY
required

Your App API key with prefix Key. See Keys & IDs.

Path Parameters

app_id
string
required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

Query Parameters

domain
string
required

The sending domain to report on. Must be an email domain configured for this app.

Example:

"mail.example.com"

start
string<date-time>
required

Start of the reporting window as an ISO 8601 timestamp, for example 2026-08-01T00:00:00Z. Must be before end and no more than 365 days ago, or 60 days ago when granularity is hourly.

Example:

"2026-08-01T00:00:00Z"

end
string<date-time>
required

End of the reporting window as an ISO 8601 timestamp, for example 2026-08-08T00:00:00Z.

Example:

"2026-08-08T00:00:00Z"

granularity
enum<string>
required

The size of each time bucket. hourly is only available for the last 60 days.

Available options:
hourly,
daily,
monthly
Example:

"daily"

providers[]
string[]

Inbox providers to include in the totals. Repeat the parameter for each provider, for example providers[]=gmail&providers[]=yahoo_us. Omit to include all providers. Accepted values: apple, att, canadian, chinese, comcast, free_fr, french, german, gmail, google_workspace, googlers, inbox_lv, italian, japanese, outlook_365, outlook_eu, outlook_us, proton, rackspace, russian, uk, united_online, yahoo_eu, yahoo_us, other_eu, other_us, and other.

Response

200

Email metrics for a sending domain over time.

events
object[]

One entry for every time bucket in the reporting window, oldest first. Buckets with no email activity are included with all metrics set to 0. Empty when the domain is not found for the app or is not currently active for sending.