curl --request POST \
--url https://api.onesignal.com/notifications/{message_id}/history \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"app_id": "YOUR_APP_ID",
"events": "sent",
"email": "<string>"
}
'import Onesignal from '@onesignal/node-onesignal';
const configuration = Onesignal.createConfiguration({
restApiKey: 'YOUR_REST_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
// string | The \"id\" of the message found in the Notification object
const notificationId: string = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88";
// GetNotificationHistoryRequestBody
const getNotificationHistoryRequestBody: Onesignal.GetNotificationHistoryRequestBody = {
events: "sent",
email: "email_example",
app_id: "app_id_example",
};
try {
const response = await apiInstance.getNotificationHistory(notificationId, getNotificationHistoryRequestBody);
console.log(response);
} catch (e) {
if (e instanceof Onesignal.ApiException) {
// `e.errorMessages` flattens any error-envelope shape to a `string[]`;
// the raw parsed body remains on `e.body`.
console.error("getNotificationHistory failed: HTTP " + e.code, e.errorMessages);
} else {
throw e;
}
}import onesignal
from onesignal.api import default_api
from onesignal.models import *
from pprint import pprint
# See configuration.py for a list of all supported configuration parameters.
# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.
# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.
configuration = onesignal.Configuration(
rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints
organization_api_key = "YOUR_ORGANIZATION_API_KEY" # Organization key is only required for creating new apps and other top-level endpoints
)
# Enter a context with an instance of the API client
with onesignal.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = default_api.DefaultApi(api_client)
notification_id = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88" # The \"id\" of the message found in the Notification object
get_notification_history_request_body = GetNotificationHistoryRequestBody(
events="sent",
email="email_example",
app_id="app_id_example",
)
try:
# Notification History
api_response = api_instance.get_notification_history(notification_id, get_notification_history_request_body)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->get_notification_history: %s\n" % e)
print("Status Code: %s" % e.status)
print("Response Body: %s" % e.body)<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure Bearer authorization: rest_api_key
$config = onesignal\client\Configuration::getDefaultConfiguration()
->setRestApiKeyToken('YOUR_REST_API_KEY')
->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');
$apiInstance = new onesignal\client\Api\DefaultApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
new GuzzleHttp\Client(),
$config
);
$notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88'; // string | The \"id\" of the message found in the Notification object
$get_notification_history_request_body = new \onesignal\client\model\GetNotificationHistoryRequestBody(); // \onesignal\client\model\GetNotificationHistoryRequestBody
try {
$result = $apiInstance->getNotificationHistory($notification_id, $get_notification_history_request_body);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->getNotificationHistory: ', $e->getMessage(), PHP_EOL;
echo 'Status Code: ', $e->getCode(), PHP_EOL;
// getErrorMessages() flattens any error-envelope shape to a string[];
// the raw body remains on getResponseBody().
echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;
echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;
} catch (\Exception $e) {
echo 'Exception when calling DefaultApi->getNotificationHistory: ', $e->getMessage(), PHP_EOL;
}package main
import (
"context"
"fmt"
"os"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
notificationId := "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88" // string | The \"id\" of the message found in the Notification object
getNotificationHistoryRequestBody := *onesignal.NewGetNotificationHistoryRequestBody() // GetNotificationHistoryRequestBody |
configuration := onesignal.NewConfiguration()
apiClient := onesignal.NewAPIClient(configuration)
restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, "YOUR_REST_API_KEY") // App REST API key required for most endpoints
resp, r, err := apiClient.DefaultApi.GetNotificationHistory(restAuth, notificationId).GetNotificationHistoryRequestBody(getNotificationHistoryRequestBody).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.GetNotificationHistory``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {
// ErrorMessages() flattens any error-envelope shape to a []string;
// the raw body remains on Body().
fmt.Fprintf(os.Stderr, "Error Messages: %v\n", apiErr.ErrorMessages())
fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body())
}
}
// response from `GetNotificationHistory`: NotificationHistorySuccessResponse
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.GetNotificationHistory`: %v\n", resp)
}require 'onesignal'
# setup authorization
OneSignal.configure do |config|
# Configure Bearer authorization: rest_api_key
config.rest_api_key = 'YOUR_REST_API_KEY'
end
api_instance = OneSignal::DefaultApi.new
notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88' # String | The \"id\" of the message found in the Notification object
get_notification_history_request_body = OneSignal::GetNotificationHistoryRequestBody.new # GetNotificationHistoryRequestBody |
begin
# Notification History
result = api_instance.get_notification_history(notification_id, get_notification_history_request_body)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->get_notification_history: #{e}"
puts "Status Code: #{e.code}"
# `e.error_messages` flattens any error-envelope shape to an Array<String>;
# the raw body remains on `e.response_body`.
puts "Error Messages: #{e.error_messages}"
puts "Response Body: #{e.response_body}"
end// Import classes:
import com.onesignal.client.ApiClient;
import com.onesignal.client.ApiException;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.*;
import com.onesignal.client.model.*;
import com.onesignal.client.api.DefaultApi;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.onesignal.com");
// Configure HTTP bearer authorization: rest_api_key
HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key");
rest_api_key.setBearerToken("YOUR_REST_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
String notificationId = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88"; // String | The \"id\" of the message found in the Notification object
GetNotificationHistoryRequestBody getNotificationHistoryRequestBody = new GetNotificationHistoryRequestBody(); // GetNotificationHistoryRequestBody |
try {
NotificationHistorySuccessResponse result = apiInstance.getNotificationHistory(notificationId, getNotificationHistoryRequestBody);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#getNotificationHistory");
System.err.println("Status code: " + e.getCode());
// getErrorMessages() flattens any error-envelope shape to a List<String>;
// the raw body remains on getResponseBody().
System.err.println("Error messages: " + e.getErrorMessages());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}using System;
using System.Collections.Generic;
using System.Diagnostics;
using OneSignalApi.Api;
using OneSignalApi.Client;
using OneSignalApi.Model;
namespace Example
{
public class GetNotificationHistoryExample
{
public static void Main()
{
Configuration config = new Configuration();
config.BasePath = "https://api.onesignal.com";
// Configure Bearer token for authorization: rest_api_key
config.AccessToken = "YOUR_REST_API_KEY";
var apiInstance = new DefaultApi(config);
var notificationId = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88"; // string | The \"id\" of the message found in the Notification object
var getNotificationHistoryRequestBody = new GetNotificationHistoryRequestBody(); // GetNotificationHistoryRequestBody |
try
{
// Notification History
NotificationHistorySuccessResponse result = apiInstance.GetNotificationHistory(notificationId, getNotificationHistoryRequestBody);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.GetNotificationHistory: " + e.Message );
Debug.Print("Status Code: "+ e.ErrorCode);
// e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList<string>;
// the raw body remains on e.ErrorContent.
Debug.Print("Error Messages: " + string.Join(", ", e.ErrorMessages));
Debug.Print("Response Body: " + e.ErrorContent);
Debug.Print(e.StackTrace);
}
}
}
}use onesignal_rust_api::apis::configuration::Configuration;
use onesignal_rust_api::apis::default_api;
use onesignal_rust_api::models;
#[tokio::main]
async fn main() {
let mut configuration = Configuration::new();
configuration.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
// Realistic values are pulled from the spec's `example:` fields where present.
let notification_id: &str = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88";
let get_notification_history_request_body: models::GetNotificationHistoryRequestBody = todo!();
match default_api::get_notification_history(&configuration, notification_id, get_notification_history_request_body).await {
Ok(resp) => println!("{:?}", resp),
Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {
// `e.error_messages()` flattens any error-envelope shape to a Vec<String>;
// the raw response remains on the ResponseError variant.
eprintln!("get_notification_history failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("get_notification_history failed: {:?}", e),
}
}{
"success": true,
"destination_url": "https://onesignal-aws-link.csv"
}{
"errors": [
"param `email` must be a valid email"
],
"success": false
}{
"errors": [
"API rate limit exceeded"
]
}{
"errors": [
"Service temporarily unavailable"
]
}Message history
View which subscriptions received a particular message
curl --request POST \
--url https://api.onesignal.com/notifications/{message_id}/history \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"app_id": "YOUR_APP_ID",
"events": "sent",
"email": "<string>"
}
'import Onesignal from '@onesignal/node-onesignal';
const configuration = Onesignal.createConfiguration({
restApiKey: 'YOUR_REST_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
// string | The \"id\" of the message found in the Notification object
const notificationId: string = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88";
// GetNotificationHistoryRequestBody
const getNotificationHistoryRequestBody: Onesignal.GetNotificationHistoryRequestBody = {
events: "sent",
email: "email_example",
app_id: "app_id_example",
};
try {
const response = await apiInstance.getNotificationHistory(notificationId, getNotificationHistoryRequestBody);
console.log(response);
} catch (e) {
if (e instanceof Onesignal.ApiException) {
// `e.errorMessages` flattens any error-envelope shape to a `string[]`;
// the raw parsed body remains on `e.body`.
console.error("getNotificationHistory failed: HTTP " + e.code, e.errorMessages);
} else {
throw e;
}
}import onesignal
from onesignal.api import default_api
from onesignal.models import *
from pprint import pprint
# See configuration.py for a list of all supported configuration parameters.
# Some of the OneSignal endpoints require ORGANIZATION_API_KEY token for authorization, while others require REST_API_KEY.
# We recommend adding both of them in the configuration page so that you will not need to figure it out yourself.
configuration = onesignal.Configuration(
rest_api_key = "YOUR_REST_API_KEY", # App REST API key required for most endpoints
organization_api_key = "YOUR_ORGANIZATION_API_KEY" # Organization key is only required for creating new apps and other top-level endpoints
)
# Enter a context with an instance of the API client
with onesignal.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = default_api.DefaultApi(api_client)
notification_id = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88" # The \"id\" of the message found in the Notification object
get_notification_history_request_body = GetNotificationHistoryRequestBody(
events="sent",
email="email_example",
app_id="app_id_example",
)
try:
# Notification History
api_response = api_instance.get_notification_history(notification_id, get_notification_history_request_body)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->get_notification_history: %s\n" % e)
print("Status Code: %s" % e.status)
print("Response Body: %s" % e.body)<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure Bearer authorization: rest_api_key
$config = onesignal\client\Configuration::getDefaultConfiguration()
->setRestApiKeyToken('YOUR_REST_API_KEY')
->setOrganizationApiKeyToken('YOUR_ORGANIZATION_API_KEY');
$apiInstance = new onesignal\client\Api\DefaultApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
new GuzzleHttp\Client(),
$config
);
$notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88'; // string | The \"id\" of the message found in the Notification object
$get_notification_history_request_body = new \onesignal\client\model\GetNotificationHistoryRequestBody(); // \onesignal\client\model\GetNotificationHistoryRequestBody
try {
$result = $apiInstance->getNotificationHistory($notification_id, $get_notification_history_request_body);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->getNotificationHistory: ', $e->getMessage(), PHP_EOL;
echo 'Status Code: ', $e->getCode(), PHP_EOL;
// getErrorMessages() flattens any error-envelope shape to a string[];
// the raw body remains on getResponseBody().
echo 'Error Messages: ', implode(', ', $e->getErrorMessages()), PHP_EOL;
echo 'Response Body: ', $e->getResponseBody(), PHP_EOL;
} catch (\Exception $e) {
echo 'Exception when calling DefaultApi->getNotificationHistory: ', $e->getMessage(), PHP_EOL;
}package main
import (
"context"
"fmt"
"os"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
notificationId := "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88" // string | The \"id\" of the message found in the Notification object
getNotificationHistoryRequestBody := *onesignal.NewGetNotificationHistoryRequestBody() // GetNotificationHistoryRequestBody |
configuration := onesignal.NewConfiguration()
apiClient := onesignal.NewAPIClient(configuration)
restAuth := context.WithValue(context.Background(), onesignal.RestApiKey, "YOUR_REST_API_KEY") // App REST API key required for most endpoints
resp, r, err := apiClient.DefaultApi.GetNotificationHistory(restAuth, notificationId).GetNotificationHistoryRequestBody(getNotificationHistoryRequestBody).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.GetNotificationHistory``: %v\n", err)
fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
if apiErr, ok := err.(*onesignal.GenericOpenAPIError); ok {
// ErrorMessages() flattens any error-envelope shape to a []string;
// the raw body remains on Body().
fmt.Fprintf(os.Stderr, "Error Messages: %v\n", apiErr.ErrorMessages())
fmt.Fprintf(os.Stderr, "Response Body: %s\n", apiErr.Body())
}
}
// response from `GetNotificationHistory`: NotificationHistorySuccessResponse
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.GetNotificationHistory`: %v\n", resp)
}require 'onesignal'
# setup authorization
OneSignal.configure do |config|
# Configure Bearer authorization: rest_api_key
config.rest_api_key = 'YOUR_REST_API_KEY'
end
api_instance = OneSignal::DefaultApi.new
notification_id = 'b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88' # String | The \"id\" of the message found in the Notification object
get_notification_history_request_body = OneSignal::GetNotificationHistoryRequestBody.new # GetNotificationHistoryRequestBody |
begin
# Notification History
result = api_instance.get_notification_history(notification_id, get_notification_history_request_body)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->get_notification_history: #{e}"
puts "Status Code: #{e.code}"
# `e.error_messages` flattens any error-envelope shape to an Array<String>;
# the raw body remains on `e.response_body`.
puts "Error Messages: #{e.error_messages}"
puts "Response Body: #{e.response_body}"
end// Import classes:
import com.onesignal.client.ApiClient;
import com.onesignal.client.ApiException;
import com.onesignal.client.Configuration;
import com.onesignal.client.auth.*;
import com.onesignal.client.model.*;
import com.onesignal.client.api.DefaultApi;
public class Example {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setBasePath("https://api.onesignal.com");
// Configure HTTP bearer authorization: rest_api_key
HttpBearerAuth rest_api_key = (HttpBearerAuth) defaultClient.getAuthentication("rest_api_key");
rest_api_key.setBearerToken("YOUR_REST_API_KEY");
DefaultApi apiInstance = new DefaultApi(defaultClient);
String notificationId = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88"; // String | The \"id\" of the message found in the Notification object
GetNotificationHistoryRequestBody getNotificationHistoryRequestBody = new GetNotificationHistoryRequestBody(); // GetNotificationHistoryRequestBody |
try {
NotificationHistorySuccessResponse result = apiInstance.getNotificationHistory(notificationId, getNotificationHistoryRequestBody);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#getNotificationHistory");
System.err.println("Status code: " + e.getCode());
// getErrorMessages() flattens any error-envelope shape to a List<String>;
// the raw body remains on getResponseBody().
System.err.println("Error messages: " + e.getErrorMessages());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}using System;
using System.Collections.Generic;
using System.Diagnostics;
using OneSignalApi.Api;
using OneSignalApi.Client;
using OneSignalApi.Model;
namespace Example
{
public class GetNotificationHistoryExample
{
public static void Main()
{
Configuration config = new Configuration();
config.BasePath = "https://api.onesignal.com";
// Configure Bearer token for authorization: rest_api_key
config.AccessToken = "YOUR_REST_API_KEY";
var apiInstance = new DefaultApi(config);
var notificationId = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88"; // string | The \"id\" of the message found in the Notification object
var getNotificationHistoryRequestBody = new GetNotificationHistoryRequestBody(); // GetNotificationHistoryRequestBody |
try
{
// Notification History
NotificationHistorySuccessResponse result = apiInstance.GetNotificationHistory(notificationId, getNotificationHistoryRequestBody);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.GetNotificationHistory: " + e.Message );
Debug.Print("Status Code: "+ e.ErrorCode);
// e.ErrorMessages flattens any error-envelope shape to an IReadOnlyList<string>;
// the raw body remains on e.ErrorContent.
Debug.Print("Error Messages: " + string.Join(", ", e.ErrorMessages));
Debug.Print("Response Body: " + e.ErrorContent);
Debug.Print(e.StackTrace);
}
}
}
}use onesignal_rust_api::apis::configuration::Configuration;
use onesignal_rust_api::apis::default_api;
use onesignal_rust_api::models;
#[tokio::main]
async fn main() {
let mut configuration = Configuration::new();
configuration.rest_api_key_token = Some("YOUR_REST_API_KEY".to_string());
// Realistic values are pulled from the spec's `example:` fields where present.
let notification_id: &str = "b3a0c8bd-3a4c-4b22-9a73-3f1a8c2d1b88";
let get_notification_history_request_body: models::GetNotificationHistoryRequestBody = todo!();
match default_api::get_notification_history(&configuration, notification_id, get_notification_history_request_body).await {
Ok(resp) => println!("{:?}", resp),
Err(e @ onesignal_rust_api::apis::Error::ResponseError(_)) => {
// `e.error_messages()` flattens any error-envelope shape to a Vec<String>;
// the raw response remains on the ResponseError variant.
eprintln!("get_notification_history failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("get_notification_history failed: {:?}", e),
}
}{
"success": true,
"destination_url": "https://onesignal-aws-link.csv"
}{
"errors": [
"param `email` must be a valid email"
],
"success": false
}{
"errors": [
"API rate limit exceeded"
]
}{
"errors": [
"Service temporarily unavailable"
]
}Overview
This API enables you to retrieve all Subscriptions that received a specific push notification or email. You can access the notification’s history for up to seven days after it was sent. Please note that notifications sent to fewer than 1,000 recipients will not record a “received” event, but they will still record “sent” events.How to Use this API
- Submit a request to generate a report.
-
Decide delivery method
- After receiving a successful response, poll the destination URL until the file becomes available. Exports typically complete within 1-3 minutes; we recommend a 10-second polling interval.
- Alternatively, you can opt to receive an email to the address specified in the optional
emailparameter when the report is ready.
Requirements
- A OneSignal Professional or Enterprise Plan.
- Enabled the “Send History via OneSignal API” option in Settings -> Integrations; notifications sent before this setting is enabled can’t be retrieved.
- Requests must be made within seven days of sending the notification.
Polling
Use thecsv_file_url property in the response to test if the report is complete. If you receive a ‘403’ error response, retry fetching the file after a short period; it only means we’re still generating the report.
Sample Report
The generated report is a simple CSV file that can be imported into any system for further processing.player_id,onesignal_id,external_id,target_channel,timestamp
"2c4fac95-7dfb-4113-9347-aba3a92ff557","ccddf35a-1233-4423-8a57-ac8c4b38eb81","a07aec27-2586-4b92-a24f-62660a1517fa","push","1628189160"
"68f5cf73-b20a-4de9-b6ee-79a863b8e7d8","d2f9f2f8-94af-4942-8183-115cef1213d5","4b66359f-3d94-4a73-806d-8ef5f0430b3d","push","1628187816"
Limitations
- Querying for
opensevents are not supported. - The
timestampcolumn is included only forclickedevents.
Headers
Your App API key with prefix Key. See Keys & IDs.
Path Parameters
The identifier of the message in UUID v4 format. Get this id in the response of your Create Message API request, the View Messages API, and in your OneSignal dashboard Message Reports.
Body
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
Specifies the type of event to retrieve. sent — retrieves all subscriptions sent the specified message. Note: sent events are not recorded for messages targeting fewer than 1,000 recipients. clicked — retrieves all subscriptions that interacted with the message. Note: There isn't a recipient count threshold for tracking clicked event.
The email address in which to deliver the report.
Was this page helpful?