OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Message Reports

OneSignal Notification delivery and statistics

Within Delivery you can view your previously Sent and Scheduled Messages. Here you can view individual message stats and export shown messages to csv.

You can sort this list by "Source" like all messages sent through the Dashboard, API, or Automated and even sort by "Device Type" like Android vs iOS vs Web browsers. Advanced Filtering allows you to filter by a time period and content.

🚧

API Notification Data Retention Limit

Notifications sent from the OneSignal API or Automated Messages are only saved for about 30 days.
You can export notification data for your records through our API or Dashboard. See Exporting Data for more details.

What each column means:

Column

Description

Type

Shows whether message was a push notification or email

Message

Contents or main body of the message.

Status

The Delivery Status of the message

Sent At

Date the message began sending. Timezone is based on your device's operating system.

Delivery

Quick stats on the Message Report.

Sent

How many devices the message was sent to.

Note: Automated Messages are sent out in batches of 10,000 notifications. This means if you are sending automated notifications to 36,000 users, you would see four distinct notifications - three with 10,000 users, and the fourth with 6,000 users.

Clicked

Percentage of users that clicked on the message sent over successfully delivered.

Created By

Hover mouse over to see the email of the administrator that sent the notification. If sent from the API we do not track who sent it.

Actions

Current Options:

  • View the notification
  • Duplicate a notification to update and re-send (Dashboard Notifications Only)
  • Delete the notification record (cannot be undone)

Delivery Status

Delivery status gives you feedback on whether the message was successfully delivered to the Google, Apple, Microsoft, Mozilla, etc. servers or is in the process of being delivered or whether there were problems during delivery.

Push Notifications

Status

Description

Delivered

OneSignal has completed sending notifications to Google, Apple, Microsoft, etc push servers.

Queued

Notifications are queued up in OneSignal and will be sent shortly

Sending

Notifications are currently sending

Scheduled

Notifications are scheduled to be delivered at the time based on Intelligent Delivery or Timezone option. They should be finished sending within 24 hours.

Canceled

You or a team member with access to your app has cancelled the delivery of this notification.

No Recipients

Recipients are no longer subscribed or no longer fit in the Segment when it was originally scheduled

Failed

Devices did not receive the notification. Details see Failed Notifications

Email Messages

Status

Description

Delivered

The user has received the email.

Clicks

Number of times an email click event is sent to OneSignal from the Email Service Provider.

Click-Through-Rate (unique)

Number of unique email click events sent to OS from the ESP.

Failed (Unsubscribed)

The user has unsubscribed after receiving your email.

Failed (errored)

Usually caused by emails sent to invalid email addresses. More details in your ESPs activity.

Bounce

The user's email server rejects the message, or sends the message back to your email service provider, due to an issue with the recipient address.

Spam

The user has marked your email as spam.

Delay

The delivery of the email has been delayed, it may successfully get delivered later.

Drop

The email service provider has dropped an email due to repeated bounces, spam reports, etc. Messages will no longer be sent to this address.

SMS

OneSignal provides two categories of SMS delivery statistics for more transparency and a better understanding of where the SMS is in the delivery pipeline.

OneSignal Delivery Statistics: (OneSignal to Twilio)
This includes

  • total number of messages you tried to send from OneSignal
  • number of messages successfully sent from OneSignal to Twilio
  • messages that failed to be delivered to Twilio or Twilio rejected those messages for reasons that might include incorrect phone number format, unsubscribed phone number, etc.
  • remaining or still in the queue on OneSignal

Twilio Delivery Statistics: (Twilio to End-User )
A message can be in the following states once OneSignal successfully delivers messages to Twilio.

  • Delivered: Twilio received confirmation from the carrier that the message has been delivered.
  • Failed Undelivered: Twilio sent these SMS but the message could not be delivered.
  • Failed Errored: Twilio could not send the message because of various reasons.
  • Remaining: Twilio has received the message request from OneSignal and these messages are queued to be sent out.

You can check the specific error details on Twilio SMS Logs.

SMS doesn’t have Outcomes data associated with it since we can not capture the opened, read, etc. states for SMS messages.


Message Report

Clicking on a notification within the Sent Messages page opens the message report. This page shows the results of sending a notification.

You can find the Notification Id in the URL of this page.

Message Report Definitions

The following are what each term here means:

Metric

Description

Total Users

The number of users that the message was sent to

Total Messages

The number of messages that OneSignal attempted to send

Push Notifications

Status

Description

Delivered

The number of notifications successfully sent to Google, Apple, Microsoft, etc server. This does not necessarily mean the devices have received these notifications.

Pending

The number of notifications that are pending delivery, but not yet delivered

Clicked

The number of clicks / taps on the push notification or email sent

Invalid

These errors are typically caused due to one of the following reasons:

- Your OneSignal Application Settings are incorrect. - These tokens belong to an app that does not match your OneSignal settings. - Some other backend error occured.

Email Messages

Status

Description

Delivered

The user has received the email.

Unsubscribe

The user has unsubscribed after receiving your email.

Bounce

The user's email server rejects the message, or sends the message back to your email service provider, due to an issue with the recipient address.

Spam

The user has marked your email as spam.

Delay

The delivery of the email has been delayed, it may successfully get delivered later.

Drop

The email service provider has dropped an email due to repeated bounces, spam reports, etc. Messages will no longer be sent to this address.


Outcomes

A cumulative graph of all Outcomes over the past 30 days, 24 hours or 1 hour.

You can toggle the graph by Platform and Attribution.

Attribution

Description

DIRECT

The Outcome happened during a session that was created due to a clicked push.

INFLUENCED

The Outcome was registered within the Attribution Window (default 24 hours) of the push but didn’t occur during a session directly initiated from a push.

Note: Only the 10 most recently sent notifications (per device) get influenced attribution

UNATTRIBUTED

The Outcome did not occur within a session started from a push click and did not occur during within the Attribution Window (default 24 hours) of a push.

TOTAL

The Total (Direct + Influenced + Unattributed)

You can add and remove Outcomes from the graph/chart and export the data.


FAQ

What does Failed Notifications mean?

There are 2 types of Failed Notifications.

1. Failed (Unsubscribed)

This means the device has unsubscribed from receiving push notifications.

For Web Push this can happen when the user has cleared their browser cookies or has opted-out of notifications from the browser settings.

For Mobile Apps this can happen when a subscribed device has either uninstalled your application or opted-out of notifications from the device settings.

For Android Mobile apps and Web, a device must receive at least two notifications to be detected as Failed (Unsubscribed). The first notification will appear to have been successfully delivered. The device must be turned on and have a network connection to silently reject this first notification.

After this, future notifications will then return as Failed (Unsubscribed) .

Once a device has been detected as unsubscribed, it will be marked as unsubscribed and future notifications will not be sent to it unless it re-subscribes to notifications again.

Example:

  • Notification 1 sent and user receives on device, then user unsubscribes.
  • Notification 2 sent, the OneSignal Dashboard shows "Delivered" but the user does not actually receive it.
  • Notification 3 sent, the OneSignal Dashboard shows Failed (Unsubscribed)
  • Notification 4 will not be sent to that device.

🚧

iOS Unsubscribe Detection

Apple changed the way it reports unsubscribe events on iOS apps.

In the past, they would report the unsubscribed device upon the 2nd notification. They stopped doing this for privacy reasons. Apple intentionally does not want token invalidation to be used as a method to detect app uninstall.

Some details provided by Apple can be found here: https://forums.developer.apple.com/thread/116445

Currently if a device unsubscribes and opens the app, we detect this right away through our SDK. However if the device uninstalls the app or unsubscribes and does not open the app, it may take several weeks for Apple to report the device unsubscribe event.

If you need to remove older devices, you can delete them using our dashboard or you can use the API Delete Call.

2. Failed (Error)

Web Push - Failed (Error) generally happens when you change one of the following:

  • the domain of your site or adding the same domain to another app ID
  • the notification data exceeds 4kb
  • there was a temporary issue with the Google Servers

Mobile Apps - Failed (Error) means the FCM sender id on Android or the Bundle ID on iOS have changed from what these devices originally subscribed under. You will need to put the original version to what the users subscribed under to fix this.

Please contact [email protected] with your OneSignal App ID and all the major changes you made to your site.

Which Email Service Providers support which statistics?

Not all email service providers provide the full range of possible email statistics.

ESP

Unsubscribe

Bounce

Spam

Invalid

Drop

Block

Sendgrid

Yes

Yes

Yes

Yes

Yes

Yes

Mailgun

Yes

Yes

Yes

Yes (bounce)

Yes

Mandrill

Yes

Yes

Yes

How do you handle suppressions like blocks, spam reports, etc?

Because OneSignal is just acting as a relay to your email service provider, we rely on the email service provider to handle communications with email servers to determine if emails are working. When an email is no longer considered working, it is suppressed by the email service provider, and will no longer send. Each email service provider has slightly different logic to determine suppressions - for instance, how many emails an email address must receive that bounce before being suppressed.

Do users receive web push notifications when the browser isn't running?

More details in our Browser Behavior Guide.

Why do the Outcomes Stats Appear to be behind?

Currently our Outcome data is bucketed in 24 hour increments in UTC time.

When converting the UTC timestamp for example 2021-01-02T00:00Z to local time, it gives us 2021-01-02T16:00 in local time.

This is truncated to 2021-01-02.

Our dashboard shows the graphs based on your timezone, so due to this truncation it will show behind (or ahead) based on how far behind (or ahead) your timezone is.

Updated about a month ago



Message Reports


OneSignal Notification delivery and statistics

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.