curl --request POST \
--url https://api.onesignal.com/notifications/count-unsaved \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"app_id": "YOUR_APP_ID",
"included_segments": [
"Active Users"
],
"excluded_segments": [
"Inactive Users"
],
"filters": [
{}
],
"include_aliases": {
"external_id": [
"YOUR_USER_EXTERNAL_ID"
]
},
"target_channel": "push"
}
'import Onesignal from '@onesignal/node-onesignal';
const configuration = Onesignal.createConfiguration({
restApiKey: 'YOUR_REST_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
// EstimateNotificationRecipientsRequest
const estimateNotificationRecipientsRequest: Onesignal.EstimateNotificationRecipientsRequest = null;
try {
const response = await apiInstance.estimateNotificationRecipients(estimateNotificationRecipientsRequest);
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("estimateNotificationRecipients 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)
estimate_notification_recipients_request = EstimateNotificationRecipientsRequest(None)
try:
# Estimate notification recipients
api_response = api_instance.estimate_notification_recipients(estimate_notification_recipients_request)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->estimate_notification_recipients: %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
);
$estimate_notification_recipients_request = new \onesignal\client\model\EstimateNotificationRecipientsRequest(['app_id' => 'YOUR_APP_ID']); // \onesignal\client\model\EstimateNotificationRecipientsRequest
try {
$result = $apiInstance->estimateNotificationRecipients($estimate_notification_recipients_request);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->estimateNotificationRecipients: ', $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->estimateNotificationRecipients: ', $e->getMessage(), PHP_EOL;
}package main
import (
"context"
"fmt"
"os"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
estimateNotificationRecipientsRequest := *onesignal.NewEstimateNotificationRecipientsRequest("YOUR_APP_ID") // EstimateNotificationRecipientsRequest |
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.EstimateNotificationRecipients(restAuth).EstimateNotificationRecipientsRequest(estimateNotificationRecipientsRequest).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.EstimateNotificationRecipients``: %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 `EstimateNotificationRecipients`: EstimateNotificationRecipientsSuccessResponse
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.EstimateNotificationRecipients`: %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
estimate_notification_recipients_request = OneSignal::EstimateNotificationRecipientsRequest.new({app_id: 'YOUR_APP_ID'}) # EstimateNotificationRecipientsRequest |
begin
# Estimate notification recipients
result = api_instance.estimate_notification_recipients(estimate_notification_recipients_request)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->estimate_notification_recipients: #{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 java.util.Arrays;
import java.util.List;
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);
EstimateNotificationRecipientsRequest estimateNotificationRecipientsRequest = new EstimateNotificationRecipientsRequest().appId("YOUR_APP_ID"); // EstimateNotificationRecipientsRequest |
try {
EstimateNotificationRecipientsSuccessResponse result = apiInstance.estimateNotificationRecipients(estimateNotificationRecipientsRequest);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#estimateNotificationRecipients");
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 EstimateNotificationRecipientsExample
{
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 estimateNotificationRecipientsRequest = new EstimateNotificationRecipientsRequest(appId: "YOUR_APP_ID"); // EstimateNotificationRecipientsRequest |
try
{
// Estimate notification recipients
EstimateNotificationRecipientsSuccessResponse result = apiInstance.EstimateNotificationRecipients(estimateNotificationRecipientsRequest);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.EstimateNotificationRecipients: " + 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 estimate_notification_recipients_request: models::EstimateNotificationRecipientsRequest = models::EstimateNotificationRecipientsRequest::new("YOUR_APP_ID".to_string());
match default_api::estimate_notification_recipients(&configuration, estimate_notification_recipients_request).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!("estimate_notification_recipients failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("estimate_notification_recipients failed: {:?}", e),
}
}{
"count": 15420,
"uncapped_count": null,
"cap_applied": false,
"mobile_suppressed": false,
"mobile_excluded_count": 0
}{
"errors": [
"<string>"
],
"success": true,
"reference": [
"<string>"
]
}{
"errors": [
"<string>"
],
"success": true,
"reference": [
"<string>"
]
}Estimated recipients
Returns the estimated number of recipients for a notification’s targeting, without creating or sending anything.
curl --request POST \
--url https://api.onesignal.com/notifications/count-unsaved \
--header 'Authorization: <authorization>' \
--header 'Content-Type: application/json' \
--data '
{
"app_id": "YOUR_APP_ID",
"included_segments": [
"Active Users"
],
"excluded_segments": [
"Inactive Users"
],
"filters": [
{}
],
"include_aliases": {
"external_id": [
"YOUR_USER_EXTERNAL_ID"
]
},
"target_channel": "push"
}
'import Onesignal from '@onesignal/node-onesignal';
const configuration = Onesignal.createConfiguration({
restApiKey: 'YOUR_REST_API_KEY',
});
const apiInstance = new Onesignal.DefaultApi(configuration);
// EstimateNotificationRecipientsRequest
const estimateNotificationRecipientsRequest: Onesignal.EstimateNotificationRecipientsRequest = null;
try {
const response = await apiInstance.estimateNotificationRecipients(estimateNotificationRecipientsRequest);
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("estimateNotificationRecipients 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)
estimate_notification_recipients_request = EstimateNotificationRecipientsRequest(None)
try:
# Estimate notification recipients
api_response = api_instance.estimate_notification_recipients(estimate_notification_recipients_request)
pprint(api_response)
except onesignal.ApiException as e:
print("Exception when calling DefaultApi->estimate_notification_recipients: %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
);
$estimate_notification_recipients_request = new \onesignal\client\model\EstimateNotificationRecipientsRequest(['app_id' => 'YOUR_APP_ID']); // \onesignal\client\model\EstimateNotificationRecipientsRequest
try {
$result = $apiInstance->estimateNotificationRecipients($estimate_notification_recipients_request);
print_r($result);
} catch (\onesignal\client\ApiException $e) {
echo 'Exception when calling DefaultApi->estimateNotificationRecipients: ', $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->estimateNotificationRecipients: ', $e->getMessage(), PHP_EOL;
}package main
import (
"context"
"fmt"
"os"
"github.com/OneSignal/onesignal-go-api/v5"
)
func main() {
estimateNotificationRecipientsRequest := *onesignal.NewEstimateNotificationRecipientsRequest("YOUR_APP_ID") // EstimateNotificationRecipientsRequest |
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.EstimateNotificationRecipients(restAuth).EstimateNotificationRecipientsRequest(estimateNotificationRecipientsRequest).Execute()
if err != nil {
fmt.Fprintf(os.Stderr, "Error when calling `DefaultApi.EstimateNotificationRecipients``: %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 `EstimateNotificationRecipients`: EstimateNotificationRecipientsSuccessResponse
fmt.Fprintf(os.Stdout, "Response from `DefaultApi.EstimateNotificationRecipients`: %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
estimate_notification_recipients_request = OneSignal::EstimateNotificationRecipientsRequest.new({app_id: 'YOUR_APP_ID'}) # EstimateNotificationRecipientsRequest |
begin
# Estimate notification recipients
result = api_instance.estimate_notification_recipients(estimate_notification_recipients_request)
p result
rescue OneSignal::ApiError => e
puts "Error when calling DefaultApi->estimate_notification_recipients: #{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 java.util.Arrays;
import java.util.List;
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);
EstimateNotificationRecipientsRequest estimateNotificationRecipientsRequest = new EstimateNotificationRecipientsRequest().appId("YOUR_APP_ID"); // EstimateNotificationRecipientsRequest |
try {
EstimateNotificationRecipientsSuccessResponse result = apiInstance.estimateNotificationRecipients(estimateNotificationRecipientsRequest);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling DefaultApi#estimateNotificationRecipients");
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 EstimateNotificationRecipientsExample
{
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 estimateNotificationRecipientsRequest = new EstimateNotificationRecipientsRequest(appId: "YOUR_APP_ID"); // EstimateNotificationRecipientsRequest |
try
{
// Estimate notification recipients
EstimateNotificationRecipientsSuccessResponse result = apiInstance.EstimateNotificationRecipients(estimateNotificationRecipientsRequest);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling DefaultApi.EstimateNotificationRecipients: " + 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 estimate_notification_recipients_request: models::EstimateNotificationRecipientsRequest = models::EstimateNotificationRecipientsRequest::new("YOUR_APP_ID".to_string());
match default_api::estimate_notification_recipients(&configuration, estimate_notification_recipients_request).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!("estimate_notification_recipients failed: {:?}", e.error_messages());
}
Err(e) => eprintln!("estimate_notification_recipients failed: {:?}", e),
}
}{
"count": 15420,
"uncapped_count": null,
"cap_applied": false,
"mobile_suppressed": false,
"mobile_excluded_count": 0
}{
"errors": [
"<string>"
],
"success": true,
"reference": [
"<string>"
]
}{
"errors": [
"<string>"
],
"success": true,
"reference": [
"<string>"
]
}Overview
The Estimated recipients API allows you to check recipient counts based on the message’s targeting settings, without creating or sending anything. The returnedcount reflects the same audience-size estimate you would see when composing a message in the OneSignal dashboard.
How to Use this API
This API is most commonly used for checking how large a draft message’s audience is going to be, before creating or sending it. When making a request to this API, use a targeting-specific subset of message fields.included_segments is required. excluded_segments, filters, include_aliases, and target_channel narrow that segment-based audience further when present.
Segments with message event or custom event filters follow the same combining rules as Create message.
Use target_channel to select which platforms to count.
Other notification targeting fields (include_subscription_ids and the other raw subscription id/token fields, and the individual isIos / isAndroid / etc. platform flags) are not read by this API.
All non-targeting notification fields (content, delivery options, and so on) are accepted, but ignored.
Headers
Your App API key with prefix Key. See Keys & IDs.
Body
The OneSignal App ID for your app. See Keys & IDs.
"YOUR_APP_ID"
Required. Segment names that define the base audience to count. Combine with excluded_segments, filters, include_aliases, and target_channel to narrow the estimate. Example: ["Active Users", "Inactive Users"]. "All" is a shorthand for every subscribed user: if the array includes "All" and the app has no segment named All, the count includes all subscribers instead of looking up a segment named All.
["Active Users"]
Narrow the count to users identified by aliases (external_id, onesignal_id, or a custom alias). Keys are alias labels and values are arrays of alias IDs. Example: { "external_id": ["extId1", "extId2"] }. Limit of 2,000 entries per REST API call.
Show child attributes
Show child attributes
{ "external_id": ["YOUR_USER_EXTERNAL_ID"] }
Response
Estimated recipient counts for the supplied targeting. No notification is created or sent.
Was this page helpful?