Overview
OneSignal records metrics at each step of a message’s lifecycle, from when OneSignal hands the message to a third-party provider (FCM, APNs, Twilio, or an email ESP) through delivery, engagement, and any follow-up events. Use this page to reconcile numbers across the dashboard, API, CSV exports, and Event Streams, or when building internal reports. Attributed, influenced, and unattributed conversions, plus yield and value, are defined in Conversion metrics, not here. Each channel section contains:- Terms: the glossary of metrics and their definitions.
- Delivery lifecycle: a visual of where each metric is captured. In-app messages have no provider lifecycle; all metrics come from the SDK. Live Activities are covered in their own section.
- Metrics mapping: the name of each metric across dashboard, API, CSV, and Event Streams surfaces.
Channel metrics comparison
Different channels have different delivery states and engagement metrics. The table below lists which metrics apply to each channel.- Some metrics have both Total and Unique variants in the per-channel tables. This applies to Opens (email) and Clicks (email, SMS/RCS, in-app).
Push terms
Push lifecycle
Push metrics mapping
Dashboard
Influenced Opens appears on push message reports and Template analytics. It is not shown in Journey node reports, Audience Activity, or Engagement Trends.
API, CSV, and Event Streams
1 The API also includes per-platform metrics for all fields except
remaining (for example, ios_clicked, android_clicked).
2 The composite Sent metric does not have a direct field in the View Message(s) API. To derive it, sum successful + failed + errored. Audience activity exports also do not include a Sent field.
3 In the View Message(s) API and Notifications CSV, the field name failed represents unsubscribed Subscriptions and errored represents delivery errors (what the dashboard calls Failed). This naming is preserved for backward compatibility.
Email terms
Total vs Unique clicks and opens
Unique clicks and opens are counted once per Subscription, regardless of how many times that user opens or clicks the same email. Total clicks and opens count every interaction, including repeats from the same user.
Email lifecycle
Email metrics mapping
Dashboard
1 The dashboard uses different labels for the same metric across surfaces: Reported as Spam (stat cards, Journey stat cards), Spam (timeseries charts), and Complained (Audience Activity). All refer to recipients who marked the message as spam or junk.
API, CSV, and Event Streams
2 Deprecated.
message.email.sent can’t be added to new Event Streams. Streams that already include it keep receiving it. Use message.email.received instead. See Deprecated event kinds.
SMS/RCS terms
SMS/RCS lifecycle
SMS/RCS metrics mapping
Dashboard
1 Audience Activity combines Failed and Rejected into a single Failed & Rejected bucket. Stat cards and Journey stat cards show them separately.
2 Stat cards and timeseries charts roll provider-side failures (Provider Errored and Provider Undelivered) up under Rejected. Failed is messages that never reached Twilio.
3 The Total Clicks and Unique Clicks stat cards combine trackable link clicks and RCS button taps, with SMS and RCS rows underneath. In the timeseries charts, Clicks and Unique Clicks count trackable link clicks only, and RCS Clicked counts RCS link taps only. The Audience Activity Clicked column counts RCS link taps only. Trackable link clicks are not recorded per recipient.
No Delivery Report is derived in the dashboard from the other stat card values rather than counted directly, so it has no counter, API field, or event of its own. It only appears once sending has finished. While a message is still going out, most messages have no delivery report yet simply because they were just sent.
API, CSV, and Event Streams
4 The sum of
failed and errored (both recorded in OneSignal’s internal system when attempting to send to Twilio) is surfaced as Failed in the dashboard.
5 Deprecated. message.sms.sent can’t be added to new Event Streams. Streams that already include it keep receiving it. Use message.sms.delivered instead. See Deprecated event kinds.
6 Notifications CSV columns use the New Format (v2) export, the default when you export from Messages > All messages. The Legacy Format (v1) export has no RCS columns. The RCS columns appear in every v2 export, whether or not the app uses RCS, and read 0 for messages without RCS activity.
7 The Notifications CSV has no SMS trackable link click column. To get SMS-only clicks from the API, subtract rcs_clicked from clicks, or rcs_unique_clicked from unique_clicks. A recipient’s clicks come from either trackable links or RCS taps, never both, because RCS content does not support trackable links.
For SMS messages, the View Message(s) API returns sms_delivered, rcs_delivered, rcs_read, clicks, and unique_clicks for every app. rcs_clicked, rcs_unique_clicked, rcs_replied, and rcs_unique_replied are returned only for apps with RCS access, and are left out of the response otherwise. See View message.
In-app terms
In-app lifecycle
There is no delivery lifecycle to consider. All metrics captured for an in-app message are from the device through the OneSignal SDK.In-app metrics mapping
Dashboard
1 We exclude “Close Button” clicks from Total Clicks on the in-app message Delivery
Report stat card.
2 While we don’t have a label on the dashboard for unique clicks, we show
unique clicks count alongside the CTR.
Event Streams
Live Activities terms
Live Activities lifecycle
Live Activities metrics mapping
Dashboard
API, CSV, and Event Streams
1 The Event Streams names are shifted relative to the dashboard concepts:
message.live_activity.sent maps to Delivered (accepted by APNs), and message.live_activity.delivered maps to Confirmed Receipt (acknowledged by the device). Wire report pipelines to the concept, not the literal event name.
2 As with push, the View Message(s) API and CSV field failed represents unsubscribed Subscriptions and errored represents delivery errors (Failed).
Retention terms
These terms apply to the Retention chart, which has no per-channel variants.
Retention counts users rather than Subscriptions, and counts every session whether or not a message gets credit for it. For how OneSignal tracks sessions and aggregates them across a user’s devices, see Sessions. For how to read the resulting curve, see Interpreting retention curves.
FAQ
Why don’t my dashboard and API counts match for push?
The dashboard Sent metric is a composite: it equals Delivered + Unsubscribed + Failed. The View Message(s) API does not return a directsent field; sum successful + failed + errored to get the equivalent value.
Why does the Push API return failed for unsubscribes and errored for delivery errors?
The field names are preserved from an earlier version of the API. In the View Message(s) API and Notifications CSV, failed means the Subscription is no longer reachable (uninstalled, cleared browser data, or opted out) and errored means a delivery error that OneSignal will retry. The dashboard labels these as Unsubscribed and Failed respectively.
What’s the difference between Total Opens and Unique Opens?
Total Opens counts every open event, including repeat opens from the same recipient. Unique Opens counts each recipient at most once. The same pattern applies to Total Clicks vs Unique Clicks for email, SMS/RCS, and in-app messages.Why does the Live Activities message.live_activity.sent event map to Delivered instead of Sent?
The event name is historical. message.live_activity.sent fires when APNs accepts the activity update (the Delivered concept), and message.live_activity.delivered fires when the device acknowledges receipt (the Confirmed Receipt concept). Use the mapping table above when configuring downstream analytics.
Why does Twilio’s delivery count sometimes differ from OneSignal’s Delivered for SMS/RCS?
OneSignal’s Delivered metric reflects carrier-confirmed receipt reported back by Twilio. Differences usually come from messages that are still in flight at the time you compare, late status callbacks from carriers, or messages that moved to Provider Undelivered after an initial acceptance. See the SMS/RCS lifecycle above for where each state is captured.How do I map dashboard labels for SMS Failed to the timeseries chart?
The stat cards and the timeseries chart use the same labels. Both show Failed (never reached Twilio) and Rejected (Provider Errored + Provider Undelivered) separately. Audience Activity combines Failed and Rejected into Failed & Rejected.Related pages
Analytics overview
Tour the dashboards, APIs, and export tools OneSignal provides for measuring performance.
Conversion metrics
Attributed, influenced, and unattributed conversions, plus yield and value.
Confirmed Receipt
Platform requirements and SDK setup for the Confirmed Receipt metric on push and Live Activities.
Event Streams
Stream real-time message events to your warehouse using the event names in this glossary.
Engagement trends
Review aggregate engagement over time using the metrics defined here.
Exporting data
Export the Notifications CSV and other data sets referenced in the mapping tables.
Journey analytics
Measure conversion and drop-off across multi-step Journeys using Journey node reports.