Basics

Appboy provides a high performance REST API to allow you to track users, send messages, export data, and more.

What is a REST API?

A REST API is a way to programatically transfer information over the web using a predefined schema. Appboy has created many different endpoints with specific requirements that will perform various actions and/or return various data. API access is done using HTTPS web requests to https://api.appboy.com/

API Definitions

Below is some terminology that you may see in the Appboy REST API documentation and what it means.

Company Secret Explanation

The company_secret was formerly included with all API requests but has been deprecated as of October 2014. This field will be ignored for all future API requests to ensure backwards compatibility.

App Group Identifier Explanation

The app_group_id indicates the app title with which the data in this request is associated. It can be found in the Developer Console section of the Appboy dashboard.

App Identifier Explanation

For Custom Events and Revenue, you may want to specify a particular variant of the App in which the event occurred. For example, if you have event data on your servers that you know came from the Android version of your app, you might want to indicate that so that it’s reflected on the dashboard. In that case, you will provide the appropriate app identifier. It can be found in the Developer Console section of the Appboy dashboard.

External User ID Explanation

The external_id serves as a unique user identifier for whom you are submitting data. This identifier should be the same as the one you set in the Appboy mobile SDK in order to avoid creating multiple profiles for the same user.

Appboy User ID Explanation

The appboy_id serves as a unique user identifier that is set by Appboy. This identifier can be used to delete users through the REST API in addition to external_ids.

For more information see:

Server-Side Only Integration

The combination of Appboy’s User Data and Messaging APIs enables powerful server-side integration options. However, we do not recommend a server-side only implementation.

The SDK supports several cases which are difficult or not possible to replicate solely via the API:

  • Transferring data in real-time
  • Automatically capturing device and session data
  • Recording anonymous user data
  • Changing states from an anonymous user to a known user
  • Native Message Types (News-Feed, In-App Messaging)
  • Triggered In-App Messages
  • Easy Push Messaging Handling
  • User Feedback capability
  • UI Components
  • Message Response Analytics
  • Local Time Delivery
  • Intelligent Delivery
  • Uninstall Tracking Helper Methods

Additionally, the native SDKs optimize network traffic, cache data offline and reduce the burden on your servers.

Effectively, this means:

  • Additional burden on the engineering team
  • Server costs to support the integration
  • Incomplete device and session data
  • Segments will not update in real-time
  • Campaigns may deliver to users who are no longer part of a segment

API Limits

  • API access for enterprise customers starts at 50,000 requests per hour and can be increased based on need.
  • API access for non-enterprise customers is limited to 50,000 requests per hour. The limit is raised from 100 requests per hour once you upgrade to a paid plan.
  • API access for free accounts is limited to 100 requests per hour.
  • Any valid request will include in its response headers the current rate limit statuses:
Header Name Description
X-RateLimit-Limit The maximum number of requests that the consumer is permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.
  • If you have questions about API limits please contact your Customer Success Manager or the Appboy Community.

API IP Whitelisting

For additional security, Appboy can whitelist IP addresses which are allowed to hit the REST APIs for a given app group. To mark specific IP addresses and subnets as whitelisted, navigate to the “Developer Console” page under App Settings. Fill in the IP addresses and subnets to whitelist in the box marked below and press save.

Developer Console

User Data

The User API allows you to track information on your users by logging data about your users that comes from outside your mobile app. You can also use this API to delete users for testing or other purposes.

All API endpoints have a data payload limit of 4MB. Attempts to post more data than 4MB will fail with an HTTP 413 Request Entity Too Large.

User Track Endpoint

This endpoint can be used to record custom events, user attributes, and purchases for users. You can include up to 50 Attributes, Event, and Purchase Objects per request. That is, you can only post attributes for up to 50 users at a time, but in the same API call you can also provide up to 50 events and up to 50 purchases.

User Track Request

POST https://api.appboy.com/users/track
Content-Type: application/json
{
   "app_group_id" : (required, string) see App Group Identifier below,
   "attributes" : (optional, array of Attributes Object),
   "events" : (optional, array of Event Object),
   "purchases" : (optional, array of Purchase Object)
}

Note: Customers using the API for server-to-server calls may need to whitelist api.appboy.com if they’re behind a firewall.

User Attributes Object Specification

An API request with any fields in the Attributes Object will create or update an attribute of that name with the given value on the specified user profile. Use the Appboy User Profile Field names below to update those special values on the user profile in the dashboard or add your own custom attribute data to the user.

{
  "external_id" : (required, string) see External User ID below,
  // Setting this flag to true will put the API in "Update Only" mode. Attributes objects regarding
  // external_ids which Appboy is unaware of will return a non-fatal error. See Server Responses for details.
  "_update_existing_only" : (optional, boolean),
  // See note below regarding anonymous push token imports
  "push_token_import" : (optional, boolean).
  // Appboy User Profile Fields
  "first_name" : "Jon",
  "email" : "bob@example.com",
  // Custom Attributes
  "my_custom_attribute" : value,
  "my_custom_attribute_2" : {"inc" : int_value},
  "my_array_custom_attribute":[ "Value1", "Value2" ],
  // Adding a new value to an array custom attribute
  "my_array_custom_attribute" : { "add" : ["Value3"] },
  // Removing a value from an array custom attribute
  "my_array_custom_attribute" : { "remove" : [ "Value1" ]},
}

Push Token Import

When importing push tokens from other systems, an external_id is not always available. To maintain communication with these users during your transition to Appboy, you can import the legacy tokens for anonymous users without providing external_id by specifying this parameter.

When specifying push_token_import as true:

  • external_id should not be specified
  • The attribute object must contain a push token
  • If the token already exists in Appboy, the request is ignored; otherwise, Appboy will create a temporary, anonymous user profile for each token to enable you to continue to message these individuals

After import, as each user launches the Appboy-enabled version of your app, Appboy will automatically move their imported push token to their Appboy user profile and clean up the temporary profile.

Custom Attribute Data Types

The following data types can be stored as a custom attribute:

  • Dates (Must be stored in the ISO 8601 format or in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format)
    • Note: Date attributes without a timezone will default to Midnight UTC (and will be formatted on the dashboard as the equivalent of Midnight UTC in the company’s timezone)
  • Strings
  • Floats
  • Booleans
  • Integers
    • Integer custom attributes may be incremented by positive or negative integers by assigning them an object with the field “inc” and the value by which you would like to increment them.
      • Example: "my_custom_attribute_2" : {"inc" : int_value},
  • Arrays
    • In addition to setting the values of an array by saying something like "my_array_custom_attribute":[ "Value1", "Value2" ] you may add to existing arrays by doing something like "my_array_custom_attribute" : { "add" : ["Value3"] }, or remove values from an array by doing something like "my_array_custom_attribute" : { "remove" : [ "Value1" ]}
    • Note: The maximum number of elements in Custom Attribute Arrays defaults to 25. The maximum for individual arrays can be increased to up to 100 in the Appboy Dashboard, under “Manage App Group -> Custom Attributes”. Arrays exceeding the maximum number of elements will be truncated to contain the maximum number of elements. For more information on Custom Attribute Arrays and their behavior, see our Documentation on Arrays.

For information regarding when you should use a Custom Event vs a Custom Attribute, see our Best Practices - User Data Collection documentation.

Appboy User Profile Fields

User Profile Field Data Type Specification  
first_name string  
last_name string  
email string  
dob (Date of Birth) string in format “YYYY-MM-DD”, e.g., 1980-12-21  
country string, we require that country codes be passed to Appboy in the ISO-3166-1 alpha-2 standard  
language string, we require that language be passed to Appboy in the ISO-639-1 standard  
time_zone string String of time zone name from IANA Time Zone Database (e.g., “America/New_York” or “Eastern Time (US & Canada)”). Only valid time zone values will be set
home_city string  
current_location object of the form {“longitude”: -73.991443, “latitude”: 40.753824}  
bio string  
gender string, “M” or “F”  
phone string of digits  
email_subscribe string, available values are “opted_in” (explicitly registered to receive email messages), “unsubscribed” (explicitly opted out of email messages), and “subscribed” (neither opted in nor out).  
push_subscribe string, available values are “opted_in” (explicitly registered to receive push messages), “unsubscribed” (explicitly opted out of push messages), and “subscribed” (neither opted in nor out).  
date_of_first_session (Date at which the user first used the app) string in ISO 8601 format or in yyyy-MM-dd'T'HH:mm:ss.SSSZ format  
date_of_last_session (Date at which the user last used the app) string in ISO 8601 format or in yyyy-MM-dd'T'HH:mm:ss.SSSZ format  
image_url string, url of image to be associated with user profile  
push_tokens array of objects with app_id and token string, e.g., [{"app_id": App Identifier, "token": "abcd"}]  
external_id string String of the unique user identifier
facebook hash containing any of id (string), likes (array of strings), num_friends (integer)  
twitter hash containing any of id (integer), screen_name (string, Twitter handle), followers_count (integer), friends_count (integer), statuses_count (integer)  
foursquare_access_token string, Foursquare OAuth3 token  
foursquare reserved, do not use  

Be aware that while you can import language, information Appboy receives from the device takes precedence, and if different, will replace the imported value the next time the user opens your app.

User Attribute Example Request

POST https://api.appboy.com/users/track
Content-Type: application/json
{
  "app_group_id" : "your app group ID",
 "attributes" : [
    {
      "external_id" : "user1",
      "first_name" : "Jon",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
  {
      "external_id" : "user2",
      "first_name" : "Jill",
      "has_profile_picture" : false,
      "push_tokens": [{"app_id": App Identifier, "token": "abcd"}]
    }
  ]
}

This example contains two User Attribute objects of the allowed 50 per API call.

Event Object Specification

{
  "external_id" : (required, string) see External User ID below,
  "app_id" : (optional, string) see App Identifier below,
  "name" : (required, string) the name of the event,
  "time" : (required, datetime as string in ISO 8601 or in `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format),
  "properties" : (optional, Properties Object) properties of the event
  // Setting this flag to true will put the API in "Update Only" mode. Event objects regarding
  // external_ids which Appboy is unaware of will return a non-fatal error. See Server Responses for details.
  "_update_existing_only" : (optional, boolean)
}

Each Event Object in the events array represents a single occurrence of a Custom Event by a particular user at the designated time value.

For information regarding when you should use a Custom Event vs a Custom Attribute, see our Best Practices - User Data Collection documentation.

Event Example Request

POST https://api.appboy.com/users/track
Content-Type: application/json
{
  "app_group_id" : "your app group ID",
 "events" : [
    {
      "external_id" : "user1",
      "app_id" : "your-app-id",
      "name" : "watched_trailer",
      "time" : "2013-07-16T19:20:30+01:00"
    },
    {
      "external_id" : "user1",
      "app_id" : "your-app-id",
      "name" : "rented_movie",
      "time" : "2013-07-16T19:20:45+01:00"
    }
  ]
}

Purchase Object Specfication

{
  "external_id" : (required, string) see External User ID below,
  "app_id" : (optional, string) see App Identifier below,
  "product_id" : (required, string) identifier for the purchase, e.g. SKU,
  "currency" : (required, string) ISO 4217 Alphabetic Currency Code,
  "price" : (required, float) value in the base currency unit (e.g. Dollars for USD, Yen for JPY),
  "quantity" : (optional, integer) the quantity purchased (defaults to 1, must be <= 100 -- currently, Appboy treats a quantity _X_ as _X_ separate purchases with quantity 1),
  "time" : (required, datetime as string in ISO 8601),
  "properties" : (optional, Properties Object) properties of the event
  // Setting this flag to true will put the API in "Update Only" mode. Event objects regarding
  // external_ids which Appboy is unaware of will return a non-fatal error. See Server Responses for details.
  "_update_existing_only" : (optional, boolean)
}

Each Purchase Object in the purchases array represents a single purchase by a particular user at a particular time.

Purchase Example Request

POST https://api.appboy.com/users/track
Content-Type: application/json
{
  "app_group_id" : "your-app-group-id",
 "purchases" : [
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "backpack",
      "currency" : "USD",
      "price" : 40.00,
      "time" : "2013-07-16T19:20:30+01:00",
      "properties" : {
        "color" : "red",
        "monogram" : "ABC",
        "checkout_duration" : 180
      }
    },
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pencil",
      "currency" : "USD",
      "price" : 2.00,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "number" : 2,
        "sharpened" : true
      }
    }
  ]
}

Properties Object

Custom events and purchases may have event properties. The “properties” values should be an Object where the keys are the property names and the values are the property values. Property names must be non-empty strings less than or equal to 255 characters, with no leading dollar signs. Property values can be integers, floats, booleans, datetimes (as strings in ISO8601 or in yyyy-MM-dd'T'HH:mm:ss.SSSZ format), or strings less than or equal to 255 characters.

User Track Responses

Upon using any of the aforementioned API requests you should receive one of the following three general responses:

Successful Message

Successful messages will be met with the following response:

{
  "message" : "success"
}

Successful Message with Non-Fatal Errors

If your message is successful but has non-fatal errors such as one invalid Event Object out of a longer list of events you will receive the following response:

{
  "message" : "success",
  "errors" : [<minor error message>]
}

Message with Fatal Errors

In the case of a success, any data that was not affected by an error in the errors array will still be processed. If your message has a fatal error you will receive the following response:

{
  "message" : <fatal error message>,
  "errors" : [<minor error message>]
}

Queued Responses

During times of maintenance, Appboy might pause real-time processing of the API. In these situations, the server will return an HTTP Accepted 202 response code and the following body, which indicates that we have received and queued the API call but have not immediately processed it. All scheduled maintenance will be posted to http://status.appboy.com ahead of time.

{
  "message" : "queued"
}

Fatal Error Response Codes

The following status codes and associated error messages will be returned if your request encounters a fatal error. Any of these error codes indicate that no data will be processed.

Error Code Reason / Cause
400 Bad Request Bad Syntax
401 Unauthorized Unknown or missing app group id
404 Not Found Unknown App Group ID (if provided)
429 Rate Limited Over rate limit
5XX Internal server error, you should retry with exponential backoff

Importing Legacy User Data

You may submit data through the Appboy API for a user who has not yet used your mobile app in order to generate a user profile. If the user subsequently uses the application all information following their identification via the SDK will be merged with the existing user profile you created via the API call. Any user behavior that is recorded anonymously by the SDK prior to identification will be lost upon merging with the existing API generated user profile.

The segmentation tool will include these users regardless of whether they have engaged with the app. If you want to exclude users uploaded via the User API whom have not yet engaged with the app you should add the filter – Session Count > 0.

User Delete Endpoint

This endpoint allows you to delete any user profile by specifying their external identifier (UserID). Up to 50 external_ids or appboy_ids can be included in a single request. Only one of external_ids or appboy_ids can be included in a single request. Please note that their associated event data will still exist in the dashboard after you delete the user.

User Delete Request

POST https://api.appboy.com/users/delete
Content-Type: application/json
{
  "app_group_id" : (required, string) App Group Identifier,
  "external_ids" : (optional, array of string) external ids for the users to delete,
  "appboy_ids" : (optional, array of string) appboy ids for the users to delete
}

Users Delete Response

Content-Type: application/json
{
  "deleted" : (required, integer) number of users successfully deleted,
  "invalid_user_ids" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user
}

Note: This action CANNOT be undone. It will PERMANENTLY remove users which may cause discrepancies in your data.

Push Notification Removal

This endpoint can be used to remove device tokens for push notifications. In general, Appboy will remove push notification tokens that are indicated to be invalid by Apple Push Notification Services, Google Cloud Messaging, Amazon Device Messaging, etc. However, based on the way in which the Apple Push Notification Service works, it is recommended that only one service poll the Apple Push Notification Feedback Service. As such, if your application is polling the APNs Feedback Service, you can use this endpoint to tell Appboy to remove push tokens and record uninstalls. Usage of this endpoint is not recommended for anything other than if your application polls the APNs Feedback Service, in which case you should email your Customer Success manager to have Appboy disable our automatic polling of the Feedback Service.

POST https://api.appboy.com/push_notification/remove
Content-Type: application/json
{
  "app_group_id" : (required, string) see App Group Identifier,
  "push_tokens" : (required, array) of Push Token Removal Objects
}

Push Token Removal Objects

{
  "app_id" : (required, string) see App Identifier,
  "token" : (required, string) push notification token string,
  "from_apns_feedback_service": (optional, boolean) whether or not this token was provided by the APNs Feedback Service,
  "uninstalled_at": (optional, integer timestamp) UNIX timestamp of when the APNs Feedback Service indicated that the app was no longer present on the device
}

You may post up to 50 Push Token Removal Objects per API call.

Sample POST Requests in Various Languages

Python

Note: This request can alternately be completed using the external library Requests.

# Necessary built-in imports to be utilized later
import json
import urllib2

# Define your static variables (app group ID, request url)
request_url = 'https://api.appboy.com/users/track'
app_group_id = "your-app-group-id"

# Define the content type as a dictionary
headers_params = {'Content-Type':'application/json'}

# Store the attribute values of your users as a list of dictionaries
attributes =[
            {'external_id':"python user ID", 'first_attribute':
             "your user's first attribute", 'second_attribute': "your user's second attribute"},
            {'external_id':"your second user's external id",'first_attribute':
             "first attribute", 'second_attribute': "second attribute"}
             ]

# Store the request data as a dictionary
data = {  'app_group_id':app_group_id,
          'attributes' : attributes   }
# Convert the data into JSON format
JSONdata = json.dumps(data)
# Create the request
req = urllib2.Request(request_url, JSONdata, headers_params)
# Open the request
f = urllib2.urlopen(req)
# Get the response code
response = f.read()
# Close the opened request
f.close
# Check that the request worked correctly
print response

# This process can alternately be completed by using the external library
# 'Requests' with the commented out code below:

# import requests
# r = requests.post(request_url, data=data, headers=headers_params)
# print r.status_code
# print r.text

Ruby (using REST Client & MultiJSON)

Note: This post request requires the downloading of the external gems Rest Client and MultiJSON

# Required libraries to import
require 'rest-client'
require 'multi_json'

# Define your static variables (app group ID, request url)
request_url = 'https://api.appboy.com/users/track'
app_group_id = 'your-app-group-id'

# Define the content type as a hash
headers_params = {'Content-Type'=>'application/json'}

# Store the attribute values of your users as an array of hashes
attributes =[
        {'external_id'=>"ruby user ID", 'first_attribute'=>
            "your user's first attribute", 'second_attribute'=> "your user's second attribute"},
        {'external_id'=>"your second user's external id",'first_attribute'=>
            "first attribute", 'second_attribute'=> "second attribute"}
        ]

# Store the request data as a hash
data = {:app_group_id => app_group_id,
        :attributes => attributes}
# Convert the data into JSON format
JSONdata = MultiJson.encode(data)
# Send and check the POST request
puts RestClient.post(request_url, JSONdata, headers_params)

PHP

<?php
# Define your static variables (app group ID, request url)
$app_group_id = 'your-app-group-id';
$request_url = 'https://api.appboy.com/users/track';

// Initialize your users by creating a map containing
// your desired attributes and associated attribute values.

$user1 = array(
       'external_id'=>"php user ID",
       'first_attribute'=> "your user's first attribute",
       'second_attribute'=> "your user's second attribute"
             );
$user2 = array(
       'external_id'=>"your second user's external id",
       'first_attribute'=> "your user's first attribute",
       'second_attribute'=> "your user's second attribute"
             );

// Note: Arrays in php are really ordered maps, hence
// the 'array' initialization associated with each user.

// Instantiate your attributes array using your previously
// defined user maps.
$attributes = array($user1, $user2);

// Organize the data to send to the API as another map
// comprised of your previously defined variables.
$postData = array(
  'app_group_id' => $app_group_id,
    'attributes' => $attributes,
);

// Create the context for the request
$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n",
        'content' => json_encode($postData)
    )
));

// Send the request
$response = file_get_contents($request_url, FALSE, $context);

// Post the response to ensure a successful request
echo $response;

?>

Messaging

Overview

The Appboy messaging API provides you with two distinct options for sending messages to your users. You can provide the message contents and configuration in the API request with the /messages/send and /messages/schedule endpoints. Alternatively, you can manage the details of your message with an API-Triggered Delivery campaign in the dashboard and just control when and to whom it is sent with the campaigns/trigger/send and campaigns/trigger/schedule endpoints. The following sections will detail the request specification for both methods.

Note: Similarly to other campaigns, you can limit the number of times a particular user can receive a Messaging API campaign by configuring re-eligibility settings in the Appboy Dashboard. Appboy will not deliver API messages to users that haven’t become re-eligible for the campaign regardless of how many API requests are sent.

Send Endpoints

The send endpoint allows you to send immediate, ad-hoc messages to designated users. If you are targeting a segment, a record of your request will be stored in the Developer Console.

Sending Messages Immediately via API Only

POST https://api.appboy.com/messages/send
Content-Type: application/json
{
   "app_group_id": (required, string) see App Group Identifier below,
   // You will need to include at least one of 'segment_id', 'external_user_ids', and 'audience'
   // Including 'segment_id' will send to members of that segment
   // Including 'external_user_ids' will send to those users
   // Including both will send to the provided user ids if they are in the segment
   "external_user_ids": (optional, array of strings) see External User ID,
   "segment_id": (optional, string) see Segment Identifier,
   "audience": (optional, Connected Audience Object) see Connected Audience,
   "campaign_id": (optional, string) see Campaign Identifier,
   "override_frequency_capping": (optional, bool) ignore frequency_capping for campaigns, defaults to false,
   "recipient_subscription_state": (optional, string) use this to send messages to only users who have opted in ('opted_in'), only users who have subscribed or are opted in ('subscribed') or to all users, including unsubscribed users ('all'), the latter being useful for transactional email messaging. Defaults to 'subscribed',
   "messages": {
     "apple_push": (optional, Apple Push Object),
     "android_push": (optional, Android Push Object),
     "windows_phone8_push": (optional, Windows Phone 8 Push Object),
     "windows_universal_push": (optional, Windows Universal Push Object),
     "kindle_push": (optional, Kindle/FireOS Push Object),
     "web_push": (optional, Web Push Object),
     "in_app_message": (optional, In-App Message Object),
     "email": (optional, Email Object)
   }
 }

Sending Messages via API Triggered Delivery

API Triggered Delivery allows you to house message content inside of the Appboy dashboard, while dictating when a message is sent, and to whom via your API. Please see this section of Appboy Academy for further details.

POST https://api.appboy.com/campaigns/trigger/send
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "campaign_id": (required, string) see Campaign Identifier,
  "trigger_properties": (optional, object) personalization key/value pairs that will apply to all users in this request
  "recipients": (optional, array) [
    {
      "external_user_id": (required, string) External Id of user to receive message,
      "trigger_properties": (optional, object) personalization key/value pairs that will apply to this user (these key/value pairs will override any keys that conflict with trigger_properties above)
    },
    ...
  ]
}

Note: The recipients array may contain up to 50 objects, with each object containing a single external_user_id string and trigger_properties object.

Note: Customers using the API for server-to-server calls may need to whitelist api.appboy.com if they’re behind a firewall.

Schedule Endpoints

The schedule endpoints allow you to send messages at a designated time and modify or cancel messages that you have already scheduled.

Create Schedule Endpoint

The create schedule endpoint allows you to schedule a message to go out at a designated time and provides you with an identifier to reference that message for updates. If you are targeting a segment, a record of your request will be stored in the Developer Console after all scheduled messages have been sent.

Scheduling Messages

POST https://api.appboy.com/messages/schedule/create
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier,
  // You will need to include at least one of 'segment_id' and 'external_user_ids'
  // Including 'segment_id' will send to members of that segment
  // Including 'external_user_ids' will send to those users
  // Including both will send to the provided user ids if they are in the segment
  "external_user_ids": (optional, array of strings) see External User ID,
  "segment_id": (optional, string) see Segment Identifier,
  "campaign_id": (optional, string) see Campaign Identifier,
  "override_messaging_limits": (optional, bool) ignore global rate limits for campaigns, defaults to false,
  "recipient_subscription_state": (optional, string) use this to send messages to only users who have opted in ('opted_in'), only users who have subscribed or are opted in ('subscribed') or to all users, including unsubscribed users ('all'), the latter being useful for transactional email messaging. Defaults to 'subscribed',
  "schedule": {
    "time": (required, datetime as ISO 8601 string) time to send the message,
    "in_local_time": (optional, bool),
    "at_optimal_time": (optional, bool),
  },
  "messages": {
    "apple_push": (optional, Apple Push Object),
    "android_push": (optional, Android Push Object),
    "windows_push": (optional, Windows Phone 8 Push Object),
    "windows8_push": (optional, Windows Universal Push Object),
    "kindle_push": (optional, Kindle/FireOS Push Object),
    "web_push": (optional, Web Push Object),
    "in_app_message" : (optional, In-App Message Object)
    "email": (optional, Email object)
    "webhook": (optional, Webhook object)
  }
}

Schedule API Triggered Campaign

POST https://api.appboy.com/campaigns/trigger/schedule/create
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier,
  "campaign_id": (required, string) see Campaign Identifier,
  // Including 'recipients' will send only to the provided user ids if they are in the campaign's segment
  "recipients": (optional, Array of Recipient Object),
  // for any keys that conflict between these trigger properties and those in a Recipient Object, the value from the
  // Recipient Object will be used
  "trigger_properties": (optional, object) personalization key/value pairs for all users in this send; see Trigger Properties,
  "schedule": {
    "time": (required, datetime as ISO 8601 string) time to send the message,
    "in_local_time": (optional, bool),
    "at_optimal_time": (optional, bool),
  }
}

The parameters for the create schedule endpoint mirror those of the send endpoint and add the schedule parameter, which allows you to specify when you want your targeted users to receive your message. If you include only the time parameter in the schedule object, all of your users will be messaged at that time. If you set in_local_time to be true, your users will receive the message at the designated date and time in their respective timezones. If in_local_timeis true, you will get an error response if the time parameter has passed in your company’s time zone. If you set at_optimal_time to be true, your users will receive the message at the designated date at the optimal time for them (regardless of the time you provide). When using local or optimal time sending, do not provide time zone designators in the value of the time parameter (e.g. just give us "2015-02-20T13:14:47" instead of "2015-02-20T13:14:47-05:00").

The response will provide you with a schedule_id that you should save in case you later need to cancel or update the message you schedule.

Create Schedule Response

Content-Type: application/json
{
  "schedule_id" : (required, string) identifier for the scheduled message that was created
}

Note: Customers using the API for server-to-server calls may need to whitelist api.appboy.com if they’re behind a firewall.

Update Schedule Endpoint

The update schedule endpoint allows you to change the schedule or message contents of a scheduled message you previously created.

Update Message Schedule

POST https://api.appboy.com/messages/schedule/update
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "schedule_id": (required, string) the schedule_id to update (obtained from the response to create schedule),
  "schedule": {
    // optional, see create schedule documentation
  },
  "messages": {
    // optional, see create schedule documentation
  }
}

The messages update schedule endpoint accepts updates to either the schedule or messages parameter or both. Your request must contain at least one of those two keys.

Update API Triggered Campaign Schedule

POST https://api.appboy.com/campaigns/trigger/schedule/update
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "campaign_id": (required, string) see Campaign Identifier,
  "schedule_id": (required, string) the schedule_id to update (obtained from the response to create schedule),
  "schedule": {
    // required, see create schedule documentation
  }
}

Any schedule or messages object that you provide will completely overwrite the one that you provided in the create schedule request or in previous update schedule requests (so if you originally provide "schedule" : {"time" : "2015-02-20T13:14:47", "in_local_time" : true} and then in your update you provide "schedule" : {"time" : "2015-02-20T14:14:47"}, your message will now be sent at the provided time in UTC, not in the user’s local time). Scheduled messages or triggers that are updated very close to or during the time they were supposed to be sent will be updated with best efforts, so last second changes could be applied to all, some, or none of your targeted users.

Delete Schedule Endpoint

The delete schedule endpoint allows you to cancel a message that you previously scheduled before it has been sent.

Delete Message Schedule

POST https://api.appboy.com/messages/schedule/delete
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "schedule_id": (required, string) the schedule_id to delete (obtained from the response to create schedule)
}

Delete Scheduled API Trigger Campaign

POST https://api.appboy.com/campaigns/trigger/schedule/delete
Content-Type: application/json
{
  "app_group_id": (required, string) see App Group Identifier below,
  "campaign_id": (required, string) see Campaign Identifier,
  "schedule_id": (required, string) the schedule_id to delete (obtained from the response to create schedule)
}

Scheduled messages or triggers that are deleted very close to or during the time they were supposed to be sent will be updated with best efforts, so last second deletions could be applied to all, some, or none of your targeted users.

Parameter Definitions

App Group Identifier

The app_group_id indicates the app title with which the data in this request is associated and authenticates the requester as someone who is allowed to send messages to the app. It must be included with every request. It can be found in the Developer Console section of the Appboy dashboard.

App Identifier

If you want to send push to a set of device tokens (instead of users), you need to indicate on behalf of which specific app you are messaging. In that case, you will provide the appropriate App Identifier in a Tokens Object. It can be found in the Developer Console section of the Appboy dashboard.

External User ID

A unique identifier for sending a message to specific users. This identifier should be the same as the one you set in the Appboy mobile SDK. You can only target users for messaging who have already been identified through the mobile SDK or the Users API. If you need to send messages to specific users who have not yet been identified to Appboy, consider attaching a Tokens Object (explained below) to your message. A maximum of 50 External User IDs are allowed in a request.

For campaign trigger endpoints, if you provide this field, the criteria will be layered with the campaign’s segments and only users who are in the list of External User IDs and the campaign’s segment will receive the message.

Segment Identifier

The segment_id indicates the segment to which the message should be sent. A Segment Identifier for each of the segments you have created can be found in the Developer Console section of the Appboy dashboard. For message endpoints, if you provide both a Segment Identifier and a list of External User IDs in a single messaging request, the criteria will be layered and only users who are in the list of External User IDs and the provided segment will receive the message.

Campaign Identifier

For messaging endpoints, the campaign_id indicates the API Campaign under which the analytics for a message should be tracked. A Campaign Identifier for each of the campaigns you have created can be found in the Developer Console section of the Appboy dashboard. If you provide a Campaign Identifier in the request body, you must provide a message_variation_id in each of the message objects indicating the represented variant of your campaign.

For campaign trigger endpoints, the campaign_id indicates the API ID of the campaign to be triggered. This field is required for all trigger endpoint requests.

Trigger Properties

When using one of the endpoints for sending a campaign with API Triggered Delivery, you have the option to provide a map of message template keys and values which can then be used to customize your message for this delivery. If you make an API request that contains an object in "trigger_properties", the values in that object can then be referenced in your message template under the api_trigger_properties namespace. For example, a request with "trigger_properties" : {"product_name" : "shoes", "product_price" : 79.99} could add the word “shoes” to the message by adding {{api_trigger_properties.${product_name}}} to the template.

Recipient Object

{
  "external_user_id": (required, string) see External User Id,
  "trigger_properties": (optional, object) personalization key/value pairs for this user; see Trigger Properties
}

Connected Audience Object

A Connected Audience is a selector that identifies the audience to send the message to. It is composed of either a single Connected Audience Filter, or several Connected Audience Filters in a logical expression using either “AND” or “OR” operators.

Multiple filter example:

{
  "AND":
    [
      Connected Audience Filter,
      {
        "OR" :
          [
            Connected Audience Filter,
            Connected Audience Filter
          ]
      },
      Connected Audience Filter
    ]
}

Connected Audience Filter

These filters are used to create an Connected Audience Object.

Custom Attribute Filter

This filter allows you to segment based on a user’s custom attribute. These filters contain up to three fields:

{
  "custom_attribute":
    {
      "custom_attribute_name": (String) the name of the custom attribute to filter on,
      "comparison": (String) one of the allowed comparisons to make against the provided value,
      "value": (String, Numeric, Boolean) the value to be compared using the provided comparison
    }
}

The custom attribute’s type determines the comparisons that are valid for a given filter.

Custom Attribute Type Allowed Comparisons
String equals, not_equal, matches_regex, does_not_match_regex, exists, does_not_exist
Array includes_value, does_not_include_value, exists, does_not_exist
Numeric equals, not_equal, greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to, exists, does_not_exist
Boolean equals, does_not_equal, exists, does_not_exist
Time less_than_x_days_ago, greater_than_x_days_ago, less_than_x_days_in_the_future, greater_than_x_days_in_the_future, after, before, exists, does_not_exist

Note: value is not required when using the exists or does_not_exist comparisons. value must be an ISO 8601 DateTime string when using the before and after comparisons.

Examples:

{
  "custom_attribute":
    {
      "custom_attribute_name": "eye_color",
      "comparison": "equals",
      "value": "blue"
    }
}

{
  "custom_attribute":
  {
    "custom_attribute_name": "favorite_foods",
    "comparison": "includes_value",
    "value": "pizza"
  }
}

{
  "custom_attribute":
  {
    "custom_attribute_name": "last_purchase_time",
    "comparison": "less_than_x_days_ago",
    "value": 2
  }
}

Push Subscription Filter

This filter allows you to segment based on a user’s push subscription status. These filters contain two fields:

{
  "push_subscription_status":
  {
    "comparison": (String) one of the two allowed comparisons listed below,
    "value": (String) one of the three allowed values listed below
  }
}
Allowed Comparisons Allowed Values
is, is_not opted_in, subscribed, unsubscribed

Email Subscription Filter

This filter allows you to segment based on a user’s email subscription status. These filters contain two fields:

{
  "email_subscription_status":
  {
    "comparison": (String) one of the two allowed comparisons listed below,
    "value": (String) one of the three allowed values listed below
  }
}
Allowed Comparisons Allowed Values
is, is_not opted_in, subscribed, unsubscribed

Apple Push Object

{
   "badge": (optional, int) the badge count after this message,
   "alert": (required unless content-available is true, string or Apple Push Alert Object) the notification message,
   // Specifying "default" in the sound field will play the standard notification sound
   "sound": (optional, string) the location of a custom notification sound within the app,
   "extra": (optional, object) additional keys and values to be sent,
   "content-available": (optional, boolean) if set, Appboy will send down the "content-available" flag with the push token,
   "category": (optional, string) define a type of notification which contains actions a user can perform in response,
   "expiry": (optional, ISO 8601 date string) if set, push messages will expire at the specified datetime,
   "custom_uri": (optional, string) a web URL, or Deep Link URI,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be an iOS Push Message),
   "asset_url": (optional, string) content URL for rich notifications for devices using iOS 10 or higher,
   "asset_file_type": (required if asset_url is present, string) file type of the asset - one of "aif", "gif", "jpg", "m4a", "mp3", "mp4", "png", or "wav"
}

-You must include an Apple Push Object in messages if you want users you have targeted to receive a push on their iOS Devices. The total number of bytes in your alert string, extra object, and other optional parameters should not exceed 1912. The Messaging API will return an error if you exceed the message size allowed by Apple. Messages that include the keys ab or aps in the extra object will be rejected.

Apple Push Alert Object

Note: In most cases, alert can just be specified in an apple_push object as a string. You should specify alert as an object only in cases where you need specific localization or Apple Watch customization.

{
   "body": (required unless content-available is true in the Apple Push Object, string) the text of the alert message,
   "title": (optional, string) a short string describing the purpose of the notification, displayed as part of the Apple Watch notification interface,
   "title_loc_key": (optional, string) the key to a title string in the `Localizable.strings` file for the current localization,
   "title_loc_args": (optional, array of strings) variable string values to appear in place of the format specifiers in title_loc_key,
   "action_loc_key": (optional, string) if a string is specified, the system displays an alert that includes the Close and View buttons, the string is used as a key to get a localized string in the current localization to use for the right button’s title instead of “View",
   "loc_key": (optional, string) a key to an alert-message string in a Localizable.strings file for the current localization,
   "loc_args": (optional, array of strings) variable string values to appear in place of the format specifiers in loc_key
}

Android Push Object

{
   "alert": (required, string) the notification message,
   "title": (required, string) the title that appears in the notification drawer,
   "extra": (optional, object) additional keys and values to be sent in the push,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be an Android Push Message),
   "priority": (optional, integer) the notification priority value,
   "send_to_sync": (optional, if set to True we will throw an error if "alert" or "title" is set),
   "collapse_key": (optional, string) the collapse key for this message,
   // Specifying "default" in the sound field will play the standard notification sound
   "sound": (optional, string) the location of a custom notification sound within the app,
   "custom_uri": (optional, string) a web URL, or Deep Link URI,
   "summary_text": (optional, string),
   "time_to_live": (optional, integer (seconds)),
   "notification_id": (optional, integer),
   "push_icon_image_url": (optional, string) an image URL for the large icon,
   "accent_color": (optional, integer) accent color to be applied by the standard Style templates when presenting this notification, an RGB integer value
}

Note: You can send “Big Picture” notifications by specifying the key appboy_image_url in the extra object. The value for appboy_image_url should be a URL that links to where your image is hosted. Images need to be cropped to a 2:1 aspect ratio and should be at least 600x300. Images used for notifications will only display on devices running Jelly Bean (Android 4.1) or higher.

Note: priority will accept values from -2 to 2, where -2 represents “MIN” priority and 2 represents “MAX”. 0 is the “DEFAULT” value. Any values sent that outside of that integer range will default to 0. For more information on which priority level to use, please see our section on Android Notification Priority.

Note: The value for the large icon push_icon_image_url should be a URL that links to where your image is hosted. Images need to be cropped to a 1:1 aspect ratio and should be at least 40x40. Images used for custom notification icons will only display on devices running Honeycomb MR1 (Android 3.1) or higher.

For more information on collapsing notifications using the collapse_key please see the Android Developer Docs

For more information on send_to_sync messages please see our section on “Silent Android Notifications”

You must include an Android Push Object in messages if you want users you have targeted to receive a push on their Android devices. The total number of bytes in your alert string and extra object should not exceed 4000. The Messaging API will return an error if you exceed the message size allowed by Google.

Kindle/FireOS Push Object

{
   "alert": (required, string) the notification message,
   "title": (required, string) the title that appears in the notification drawer,
   "extra": (optional, object) additional keys and values to be sent in the push,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be an Kindle/FireOS Push Message),
   "priority": (optional, integer) the notification priority value,
   "collapse_key": (optional, string) the collapse key for this message,
   // Specifying "default" in the sound field will play the standard notification sound
   "sound": (optional, string) the location of a custom notification sound within the app,
   "custom_uri": (optional, string) a web URL, or Deep Link URI
}

Note: priority will accept values from -2 to 2, where -2 represents “MIN” priority and 2 represents “MAX”. 0 is the “DEFAULT” value. Any values sent that outside of that integer range will default to 0.

Web Push Object

{
   "alert": (required, string) the notification message,
   "title": (required, string) the title that appears in the notification drawer,
   "extra": (optional, object) additional keys and values to be sent in the push,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be an Kindle/FireOS Push Message),
   "custom_uri": (optional, string) a web URL,
   "image_url": (optional, string) url for image to show,
   "time_to_live": (optional, integer (seconds))
}

Note: The value for image_url should be a URL that links to where your image is hosted. Images need to be cropped to a 1:1 aspect ratio.

Windows Phone 8 Push Object

{
   "push_type": (optional, string) must be "toast",
   "toast_title": (optional, string) the notification title,
   "toast_content": (required, string) the notification message,
   "toast_navigation_uri": (optional, string) page uri to send user to,
   "toast_hash": (optional, object) additional keys and values to send,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be a Windows Phone 8 Push Message)
}

Windows Universal Push Object

See the Windows Universal toast template catalog for details on the options for push_type below.

{
   "push_type": (required, string) one of: "toast_text_01", "toast_text_02", "toast_text_03", "toast_text_04", "toast_image_and_text_01", "toast_image_and_text_02", "toast_image_and_text_03", or "toast_image_and_text_04",
   "toast_text1": (required, string) the first line of text in the template,
   "toast_text2": (optional, string) the second line of text (for templates with > 1 line of text),
   "toast_text3": (optional, string) the third line of text (for the *_04 templates),
   "toast_text_img_name": (optional, string) the path for the image for the templates that include an image,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under (must be a Windows Universal Push Message),
   "extra_launch_string": (optional, string) used to add deep linking functionality by passing extra values to the launch string
}

Note: For more information on using the extra_launch_string parameter for deep linking, see Deep Linking with Windows Universal. For information regarding what a deep link is, please see our FAQ Section.

In-App Message Object Specification

See our Guide to Best Practices for In-App Messages for the details on the different types of in-app messages available.

{
   "type" : (optional, string) one of "SLIDEUP" OR "MODAL" or "FULL", defaults to "SLIDEUP",
   // For "SLIDEUP" messages, old versions of the SDK only support some of the features, so set this to false to avoid sending messages that would not make sense as an older version of the slideups (i.e. includes an image that is referenced by the message). This is not applicable for "MODAL" or "FULL" messages, which are always only sent to new versions
   "also_send_to_slideup_only_versions" : (optional, boolean), defaults to true,
   "message" : (required, string) 140 characters max,
   // all colors should be 8-digit hex strings plus a leading "0x", for example "0xFF00AA88"
   // see http://developer.android.com/reference/android/graphics/Color.html for specifications
   "message_text_color" : (optional, string) hex value for colors, defaults to black or white depending on message type,
   "header" : (optional, string) the header shown, not shown if excluded,
   "header_text_color" : (optional, string) hex value for colors, defaults to black or white depending on message type,
   "background_color" : (optional, string) hex value for colors, defaults to black or white depending on message type,
   "close_button_color" : (optional, string) hex value for colors, defaults to black
   "slide_from" : (optional, string) "TOP" OR "BOTTOM" for "STANDARD" messages, defaults to "BOTTOM",
   "message_close" : (optional, string) "SWIPE" OR "AUTO_DISMISS", defaults to "AUTO_DISMISS",
   // icon should be 4-digit hex string without the leading "0x" from http://fortawesome.github.io/Font-Awesome/cheatsheet/
   // for example, "f042" for the first icon, fa-adjust [&#xf042;]
   // if both image_url and icon are present, image_url will be used
   "icon": (optional, string) Font Awesome icon hex value,
   "icon_color" : (optional, string) hex value for colors, defaults to white,
   "icon_background_color" : (optional, string) hex value for colors, defaults to blue,
   "image_url" : (optional, string) url for image to show when type is "FULL", overrides "icon" if both are present,
   "buttons" : (optional, Array of Button Objects) buttons to show, at most 2 allowed,
   "extras" : (optional, valid Key Value Hash), extra hash,
   // click actions and uri are not applicable if there are buttons and type is MODAL or FULL
   "ios_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "android_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "windows_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "windows8_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "kindle_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "android_china_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "web_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "ios_uri" : (optional, string) valid http or protocol uri,
   "android_uri" : (optional, string) valid http or protocol uri,
   "windows_uri" : (optional, string) valid http or protocol uri,
   "windows8_uri" : (optional, string) valid http or protocol uri,
   "kindle_uri" : (optional, string) valid http or protocol uri,
   "android_china_uri" : (optional, string) valid http or protocol uri,
   "web_uri" : (optional, string) valid http or protocol uri,
   "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under
}

The In-App Message Object should be included in messages when you would like to also deliver an in-app message with the given content to the targeted users.

Button Object

{
   "text": (required, string) text shown on button,
   "text_color": (optional, string) hex value for colors, defaults to white,
   "background_color": (optional, string) hex value for colors, defaults to blue,
   "ios_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "android_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "windows_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "windows8_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "kindle_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "android_china_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "web_click_action" : (optional, string) "NONE" OR "NEWS_FEED" OR "URI", defaults to "NONE",
   "ios_uri" : (optional, string) valid http or protocol uri,
   "android_uri" : (optional, string) valid http or protocol uri,
   "windows_uri" : (optional, string) valid http or protocol uri,
   "windows8_uri" : (optional, string) valid http or protocol uri,
   "kindle_uri" : (optional, string) valid http or protocol uri,
   "android_china_uri" : (optional, string) valid http or protocol uri,
   "web_uri" : (optional, string) valid http or protocol uri,
}

Email Object Specification

{
  "app_id": (required, string) see App Identifier above,
  "subject": (optional, string),
  "from": (required, valid email address in the format "Display Name <email@address.com>"),
  "reply_to": (optional, valid email address in the format "email@address.com" - defaults to your app group's default reply to if not set),
  "body": (required unless email_template_id is given, valid HTML),
  "plaintext_body": (optional, valid plaintext, defaults to autogenerating plaintext from "body" when this is not set),
  "email_template_id": (optional, string) If provided, we will use the subject/body values from the given email template UNLESS they are specified here, in which case we will override the provided template,
  "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under,
  "extras": (optional, valid Key Value Hash), extra hash - for SendGrid customers, this will be passed to SendGrid as Unique Arguments,
  "headers": (optional, valid Key Value Hash), hash of custom extensions headers. Currently, only supported for SendGrid customers
}

Note: An email_template_id can be retrieved from the bottom of any Email Template created within the dashboard. Below is an example of what this ID looks like:

Email Template ID

Webhook Object Specification

{
  "url": (required, string),
  "request_method": (required, string) one of "POST", "PUT", "DELETE", or "GET",
  "request_headers": (optional, Hash) key/value pairs to use as request headers,
  "body": (optional, string) if you want to include a JSON object, make sure to escape quotes and backslashes,
  "message_variation_id": (optional, string) used when providing a campaign_id to specify which message variation this message should be tracked under
}

Server Responses

If your POST payload was accepted by our servers, then successful messages will be met with the following response:

{
  "message" : "success"
}

Note that success only means that the RESTful API payload was correctly formed and passed onto our push notification or email or other messaging services. It does not mean that the messages were actually delivered, as additional factors could prevent the message from being delivered (e.g., a device could be offline, the push token could be rejected by Apple’s servers, you may have provided an unknown user ID, etc.)

If your message is successful but has non-fatal errors you will receive the following response:

{
  "message" : "success", "errors" : [<minor error message>]
}

In the case of a success, any messages that were not affected by an error in the errors array will still be delivered. If your message has a fatal error you will receive the following response:

{
  "message" : <fatal error message>, "errors" : [<minor error message>]
}

Queued Responses

During times of maintenance, Appboy might pause real-time processing of the API. In these situations, the server will return an HTTP Accepted 202 response code and the following body, which indicates that we have received and queued the API call but have not immediately processed it. All scheduled maintenance will be posted to http://status.appboy.com ahead of time.

{
  "message" : "queued"
}

Fatal Errors

The following status codes and associated error messages will be returned if your request encounters a fatal error. Any of these error codes indicate that no messages will be sent.

  • 400 Bad Request - Bad syntax.
  • 400 No Recipients - There are no external IDs or segment IDs or no push tokens in the request
  • 400 Invalid Campaign ID - No Messaging API Campaign was found for the campaign ID you provided
  • 400 Message Variant Unspecified - You provide a campaign ID but no message variation ID
  • 400 Invalid Message Variant - You provided a valid campaign ID, but the message variation ID doesn’t match any of that campaign’s messages
  • 400 Mismatched Message Type - You provided a message variation of the wrong message type for at least one of your messages
  • 400 Invalid Extra Push Payload - You provide the “extra” key for either “apple_push” or “android_push” but it is not a dictionary
  • 400 Max input length exceeded - Caused by:
    • More than 50 external ids
  • 400 No message to send - No payload is specified for the message
  • 400 Slideup Message Length Exceeded - Slideup message > 140 characters
  • 400 Apple Push Length Exceeded - JSON payload > 1912 bytes
  • 400 Android Push Length Exceeded - JSON payload > 4000 bytes
  • 400 Bad Request - Cannot parse send_at datetime
  • 400 Bad Request - in_local_time is true but time has passed in your company’s time zone
  • 401 Unauthorized - Unknown or missing app group id
  • 403 Forbidden - Rate plan doesn’t support or account is otherwise inactivated
  • 404 Not Found - Unknown App Group ID
  • 429 Rate limited - Over rate limit
  • 5XX - Internal server error, you should retry your request with exponential backoff

API Limits

  • You can post up to 50 events per request
  • API access for enterprise customers is unlimited. With the understanding that you can get whatever throughput your use case requires and you are able to pay for.
  • API access for non-enterprise customers is limited to 100 requests per hour.
  • If you have questions about API limits please contact your Customer Success manager.

Sample Requests in Various Languages

Python

Note: This request can alternatively be completed using the external library Requests.

# Necessary built-in imports to be utilized later
import json
import urllib2

# Define your static variables (app group ID, request url)
request_url = 'https://api.appboy.com/messages/send'
app_group_id = 'your app group id'

# Determine which users you want to message
external_user_ids = ['external user id 1', 'external user id 2']

# Define the content type as a dictionary
headers_params = {'Content-Type':'application/json'}

# Define the contents of your message(s)
android_noti = {"alert": "your message",
                "title": "your message title"}
apple_noti = {"alert": "your message",
              "badge": 'remaining badge count (as an integer)'}
# Instantiate your messages variable as a dictionary
messages = {"android_push" : android_noti,
            "apple_push": apple_noti}

# Store the request data as a dictionary
data = {'app_group_id': app_group_id,
        'external_user_ids': external_user_ids,
        'messages' : messages}

# CAMPAIGN TRIGGER ENDPOINT VARIABLES ONLY

request_url = 'https://api.appboy.com/campaigns/trigger/send'
campaign_id = 'your campaign id'

data = {'app_group_id': app_group_id,
        'campaign_id': campaign_id,
        'external_user_ids': external_user_ids}

# END ENDPOINT-SPECIFIC VARIABLES

# Convert the data into JSON format
JSONdata = json.dumps(data)
# Create the request
req = urllib2.Request(request_url, JSONdata, headers_params)
# Open the request
f = urllib2.urlopen(req)
# Get the response code
response = f.read()
# Close the opened request
f.close()
# Check that the request worked correctly
print response

Ruby (using REST Client & MultiJSON):

Note: This post request requires the downloading of the external gems Rest Client and MultiJSON

# Required libraries to import
require 'rest-client'
require 'multi_json'

app_group_id = 'your app group id'

# Decide which users you wish to target
external_user_ids = ['external user id 1', 'external user id 2']

# Define the content type as a hash
headers_params = {'Content-Type'=>'application/json'}

# Define the contents of your messages
android_noti = {:alert => 'your message',
                :title => 'your message title'}
apple_noti = {:alert => 'your message',
              :badge => 'remaining badge count (as an integer)'}
# Instantiate the messages array        
messages = {'android_push' => android_noti,
            'apple_push' => apple_noti}

# Organize the data to send to the API as a hash
# comprised of your previously defined variables.
data = {:app_group_id => app_group_id,
        :external_user_ids => external_user_ids,
        :messages => messages}

# CAMPAIGN TRIGGER ENDPOINT VARIABLES ONLY

request_url = 'https://api.appboy.com/campaigns/trigger/send'
campaign_id = 'your campaign id'

# Organize the data to send to the API as a hash
# comprised of your previously defined variables.
data = {:app_group_id => app_group_id,
        :campaign_id => campaign_id,
        :external_user_ids => external_user_ids}

# END ENDPOINT-SPECIFIC VARIABLES

# Convert the data into JSON format
JSONdata = MultiJson.encode(data)
# Send and check the POST request
puts RestClient.post(request_url, JSONdata, headers_params)

PHP

<?php
$app_group_id = 'your app group ID';

// Determine the users you plan to message
$external_user_ids = array('external user id 1', 'external user id 2');

// Establish the contents of your messages array
$android_noti = array('alert' => 'your message',
                      'title' => 'your message title');
$apple_noti = array('alert' => 'your message',
                    'badge' => 'remaining badge count (as an integer)');
// Instantiate the messages array
$messages = array('android_push' => $android_noti,
                  'apple_push' => $apple_noti);

// Organize the data to send to the API as another map
// comprised of your previously defined variables.
$postData = array(
  'app_group_id' => $app_group_id,
  'external_user_ids' => $external_user_ids,
  'messages' => $messages,
);

// CAMPAIGN TRIGGER ENDPOINT VARIABLES ONLY

$request_url = 'https://api.appboy.com/campaigns/trigger/send';
$campaign_id = 'your campaign id';

// Organize the data to send to the API as another map
// comprised of your previously defined variables.
$postData = array(
  'app_group_id' => $app_group_id,
  'campaign_id' => $campaign_id,
  'external_user_ids' => $external_user_ids,
);

// END ENDPOINT-SPECIFIC VARIABLES

// Create the context for the request
$context = stream_context_create(array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n",
        'content' => json_encode($postData)
    )
));

// Send the request
$response = file_get_contents($request_url, FALSE, $context);

// Print the response to ensure a successful request
echo $response;

?>

Email Sync

Users’ email subscription status can be updated and retrieved via Appboy using a RESTful API. You can use the API to setup bi-directional sync between Appboy and other email systems or your own database.

API Specification

All API requests are made over HTTPS to https://api.appboy.com/. Below are the paths for each email sync endpoint:

URL HTTP Verb Functionality
/email/unsubscribes GET Retrieving Objects
/email/status POST Creating Objects
/email/bounce/remove POST Removing Objects
/email/spam/remove POST Removing Objects

Querying Unsubscribed Emails

GET https://api.appboy.com/email/unsubscribes

Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
start_date No String in YYYY-MM-DD format Start date of the range to retrieve unsubscribes, must be earlier than end_date. This will be taken as UTC time by the API.
end_date No String in YYYY-MM-DD format End date of the range to retrieve unsubscribes. This will be taken as UTC time by the API
limit No Integer Optional field to limit the number of results returned. Defaults to 100
offset No Integer Optional beginning point in the list to retrieve from
email No String If provided, we will return whether or not the user has unsubscribed

Note: You must provide either an email or a start_date, and an end_date.

Changing Email Subscription Status

POST https://api.appboy.com/email/status

This endpoint allows you to set the email subscription state for your users. Users can be “opted_in”, “unsubscribed”, or “subscribed” (not specifically opted in or out).

You can set the email subscription state for an email address that is not yet associated with any of your users within Appboy. When that email address is subsequently associated with a user, the email subscription state that you uploaded will be automatically set.

Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
email Yes String or Array String email address to modify, or an Array of up to 50 email addresses to modify.
subscription_state Yes String Either “subscribed”, “unsubscribed”, or “opted_in”.

Removing Hard Bounces

POST https://api.appboy.com/email/bounce/remove

This endpoint allows you to remove email addresses from your Appboy bounce list. We will also remove them from the bounce list maintained by your email provider.

Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
email Yes String or Array String email address to modify, or an Array of up to 50 email addresses to modify.

Removing Spam

This endpoint allows you to remove email addresses from your Appboy spam list. We will also remove them from the spam list maintained by your email provider.

POST https://api.appboy.com/email/spam/remove

Parameter Required Data Type Description
app_group_id Yes String see App Group Identifier in Parameter Definitions
email Yes String or Array String email address to modify, or an Array of up to 50 email addresses to modify.

Example Unsubscribe CURL

The following example CURL demonstrates how to unsubscribe a user from receiving email via the Appboy APIs:

curl -X POST -H "Content-Type: application/json" -d '{"app_group_id":"YOUR_APP_GROUP_ID","email":"EMAIL_TO_UNSUBSCRIBE","subscription_state":"unsubscribed"}' https://api.appboy.com/email/status

Export

User Export

Users by UserID Endpoint

This endpoint allows you to export data from any user profile by specifying their external identifier (UserID). Up to 50 external_ids can be included in a single request.

POST https://api.appboy.com/users/export/ids
Content-Type: application/json
{
    "app_group_id" : (required, string) App Group Identifier,
    "external_ids" : (required, array of string) external ids for the users to export,
    "fields_to_export" : (optional, array of string) name of user data fields to export, e.g. ['first_name', 'email', 'purchases'], defaults to all if not provided
}

Users by UserID Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "users" : (optional, array of object) the data for each of the exported users,
    "invalid_user_ids" : (optional, array of string) each of the identifiers provided in the request that did not correspond to a known user
}

For an example of the data that is accessible via this endpoint see the Sample User Export Output section of this documentation.

Users by UserID Example CURL

curl -X POST -H "Content-Type: application/json" -d '{"app_group_id":"YOUR_APP_GROUP_ID_FROM_DEVELOPER_CONSOLE","external_ids":["external_id1", "external_id2"],"fields_to_export": ["field1", "field2"]}' https://api.appboy.com/users/export/ids

Users by Segment Endpoint

This endpoint allows you to export all the users within a segment. User data is exported as multiple files of user JSON objects separated by new lines (i.e. one JSON object per line).

If you have added your S3 credentials to Appboy, then each file will be uploaded in your bucket as a zip file with the key format that looks like “segment-export/SEGMENT_ID/YYYY-MM-dd/RANDOM_UUID-TIMESTAMP_WHEN_EXPORT_STARTED/filename.zip”. We will create 1 file per 5,000 users to optimize processing. You can then unzip the files and concatenate all of the csv files to a single file if needed.

If you do not have S3 credentials provided, the response to the request provides the url where a zip file containing all the user files can be downloaded. The URL will only become a valid location once the export is ready. Please be aware that if you do not have S3 credentials, there is a limitation on the amount of data that you can export from this endpoint. In most cases this limit is about 5 gigabytes, which is usually around 500,000 to 1 million user profiles. In the event that you have not added S3 credentials and you attempt to export a segment that is too large, Appboy will notify the person who last edited the segment that you must provide S3 credentials in order to export the segment.

In either scenario, you may optionally provide a callback_endpoint to be notified when the export is ready. If the callback_endpoint is provided, we will make a post request to the provided address when the download is ready. The body of the post will be “success”:true. If you have not added S3 credentials to Appboy, then the body of the post will additionally have the attribute “url” with the download url as the value.

Larger user bases will result in longer export times. For example, an app with 20 million users could take an hour or more.

POST https://api.appboy.com/users/export/segment
Content-Type: application/json
{
    "app_group_id" : (required, string) App Group Identifier,
    "segment_id" : (required, string) identifier for the segment to be exported,
    "callback_endpoint" : (optional, string) endpoint to post a download url to when the export is available,
    "fields_to_export" : (optional, array of string) name of user data fields to export, e.g. ['first_name', 'email', 'purchases'], defaults to all if not provided
}

Note: The segment_id for a given segment can be found on our Developer Console within your dashboard or you can use the Segment List Endpoint.

Users by Segment Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "object_prefix": (required, string) the filename prefix that will be used for the JSON file produced by this export, e.g. 'bb8e2a91-c4aa-478b-b3f2-a4ee91731ad1-1464728599',
    "url" : (optional, string) the url where the segment export data can be downloaded if you do not have your own S3 credentials
}

Note: Once made available, the url will only be valid for a few hours. As such, we highly recommend that you add your own S3 credentials to Appboy.

Users by Segment Example CURL

curl -X POST -H "Content-Type: application/json" -d '{"app_group_id":"YOUR_APP_GROUP_ID_FROM_DEVELOPER_CONSOLE","segment_id":"INSERT_SEGMENT_ID_HERE","fields_to_export": ["field1", "field2"]}' https://api.appboy.com/users/export/segment

Sample User Export File Output

User export object (we will include the least data possible - if a field is missing from the object it should be assumed to be null, false, or empty):

{
    "external_id" : (string),
    "appboy_id": (string),
    "first_name" : (string),
    "last_name" : (string),
    "email" : (string),
    "dob" : (string) date for the user's date of birth,
    "home_city" : (string),
    "country" : (string),
    "phone" : (string),
    "language" : (string) ISO-639 two letter code,
    "time_zone" : (string),
    "last_coordinates" : (array of float) [lon, lat],
    "gender" : (string) "M" | "F",
    "total_revenue" : (float),
    "attributed_campaign" : (string),
    "attributed_source" : (string),
    "attributed_adgroup" : (string),
    "attributed_ad" : (string),
    "push_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "email_subscribe" : (string) "opted_in" | "subscribed" | "unsubscribed",
    "custom_attributes" : (object) custom attribute key value pairs,
    "custom_events" : [
        {
            "name" : (string),
            "first" : (string) date,
            "last" : (string) date,
            "count" : (int)
        },
        ...
    ],
    "purchases" : [
        {
            "name" : (string),
            "first" : (string) date,
            "last" : (string) date,
            "count" : (int)
        },
        ...
    ],
    "devices" : [
        {
            "model" : (string),
            "os" : (string),
            "carrier" : (string),
            "idfv" : (string) only included for iOS devices,
            "idfa" : (string) only included for iOS devices when IDFA collection is enabled,
            "ad_tracking_enabled" : (bool)
        },
        ...
    ],
    "push_tokens" : [
        {
            "app" : (string) app name,
            "platform" : (string),
            "token" : (string)
        },
        ...
    ],
    "apps" : [
        {
            "name" : (string),
            "platform" : (string),
            "version" : (string),
            "sessions" : (string),
            "first_used" : (string) date,
            "last_used" : (string) date
        },
        ...
    ],
    "campaigns_received" : [
        {
            "name" : (string),
            "last_received" : (string) date,
            "engaged" : {
                "opened_email" : (bool),
                "opened_push" : (bool),
                "clicked_email" : (bool),
                "clicked_in_app_message" : (bool)
            },
            "converted" : (bool),
            "api_campaign_id" : (string),
            "variation_name" : (optional, string) exists only if it is a multivariate campaign,
            "variation_api_id" : (optional, string) exists only if it is a multivariate campaign,
            "in_control" : (optional, bool) exists only if it is a multivariate campaign
        },
        ...
    ],
    "cards_clicked" : [
        {
            "name" : (string)
        },
        ...
    ]
}

Segment Export

Segment List Endpoint

This endpoint allows you to export a list of segments, each of which will include it’s name, Segment Identifier, and whether it has analytics tracking enabled. The segments are returned in groups of 100 sorted by time of creation, most recent first. Archived segments are not included.

GET https://api.appboy.com/segments/list

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
page No Integer The page of segments to return, defaults to 0 (returns the first set of up to 100)

Example URL: https://api.appboy.com/segments/list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1

Segment List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "segments" : [
        {
            "id" : (string) Segment Identifier,
            "name" : (string) segment name,
            "analytics_tracking_enabled" : (boolean) whether the segment has analytics tracking enabled,
            "tags" : (array) tag names associated with the segment
        },
        ...
    ]
}

Segment Analytics Endpoint

This endpoint allows you to retrieve a daily series of the size of a segment over time for a segment with analytics tracking enabled.

GET https://api.appboy.com/segments/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
segment_id Yes String Segment Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request

Note: The segment_id for a given segment can be found on our Developer Console within your dashboard or you can use the Segment List Endpoint.

Example URL: https://api.appboy.com/segments/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&segment_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064&length=7&ending_at=2014-12-10T23:59:59-05:00

Segment Analytics Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "size" : (int) size of the segment on that date
        },
        ...
    ]
}

Segment Details Endpoint

This endpoint allows you to retrieve relevant information on the segment, which can be identified by the segment_id.

GET https://api.appboy.com/segments/details

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
segment_id Yes String Segment Identifier

Note: The segment_id for a given segment can be found on our Developer Console within your dashboard or you can use the Segment List Endpoint.

Example URL: https://api.appboy.com/segments/details?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&segment_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Segment Details Endpoint API Response

Content-Type: application/json
{
      "message": (required, string) the status of the export, returns 'success' when completed without errors,
      "created_at" : (string) date created as ISO 8601 date,
      "updated_at" : (string) date last updated as ISO 8601 date,
      "name" : (string) segment name,
      "description" : (string) human-readable description of filters,
      "tags" : (array) tag names associated with the segment
}

Campaign Export

Campaign List Endpoint

This endpoint allows you to export a list of campaigns, each of which will include its name, Campaign Identifier, and whether it is an API Campaign. The campaigns are returned in groups of 100 sorted by time of creation, first with the most recent.

Note: Archived campaigns will not be included in the API response unless include_archived is specified. Paused campaigns, however, will be returned by default.

GET https://api.appboy.com/campaigns/list

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
page No Integer The page of campaigns to return, defaults to 0 (returns the first set of up to 100)
include_archived No Boolean Whether or not to include archived campaigns, defaults to false

Example URL: https://api.appboy.com/campaigns/list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1&include_archived=true

Campaign List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "campaigns" : [
        {
            "id" : (string) Campaign Identifier,
            "name" : (string) campaign name,
            "is_api_campaign" : (boolean) whether the campaign is an API Campaign,
            "tags" : (array) tag names associated with the campaign
        },
        ...
    ]
}

Campaign Analytics Endpoint

This endpoint allows you to retrieve a daily series of various stats for a campaign over time.

GET https://api.appboy.com/campaigns/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
campaign_id Yes String Campaign Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request

Note: The campaign_id for API campaigns can be found on the Developer Console page and the campaign details page within your dashboard or you can use the Campaign List Endpoint.

Example URL: https://api.appboy.com/campaigns/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&campaign_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064&length=7&ending_at=2014-12-10T23:59:59-05:00

Campaign Analytics Endpoint API Response

Multi-channel Response
Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "conversions" : (int),
            "revenue": (float),
            "conversions_by_send_time": (int),
            "messages" : {
                "email" : [
                    {
                        "sent" : (int),
                        "opens" : (int),
                        "unique_opens" : (int),
                        "clicks" : (int),
                        "unique_clicks" : (int),
                        "unsubscribes" : (int),
                        "bounces_including_dropped" : (int),
                        "delivered" : (int),
                        "reported_spam" : (int)
                    },
                    ...
                ],
                "in_app_message" : [
                    {
                        "sent" : (int),
                        "impressions" : (int),
                        "opens" : (int)
                    },
                    ...
                ],
                "android_push" : [
                    {
                        "sent" : (int),
                        "direct_opens" : (int),
                        "total_opens" : (int),
                        "bounces" : (int)
                    },
                    ...
                ],
                ...
            }
        },
        ...
    ]
}
Multi-variate Response
Content-Type: application/json
{
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "conversions" : (int),
            "revenue": (float),
            "conversions_by_send_time": (int),
            "messages" : {
                "android_push" : [
                    {
                        "variation_name" : (optional, string),
                        "sent" : (int),
                        "direct_opens" : (int),
                        "total_opens" : (int),
                        "bounces" : (int),
                        "unique_recipients" (int),
                        "conversions" : (optional, int),
                        "revenue" : (optional, float),
                        "conversions_by_send_time" : (optional, int)
                    },
                    {
                        "variation_name" : (optional, string),
                        "sent" : (int),
                        "direct_opens" : (int),
                        "total_opens" : (int),
                        "bounces" : (int),
                        "unique_recipients" (int),
                        "conversions" : (optional, int),
                        "revenue" : (optional, float),
                        "conversions_by_send_time" : (optional, int)
                    },
                    {
                        "variation_name" : "Control Group",
                        "enrolled" : (int),
                        "unique_recipients" (int),
                        "conversions" : (optional, int),
                        "revenue" : (optional, float),
                        "conversions_by_send_time" : (optional, int)
                    },
                    ...
                ],
                ...
            }
        },
        ...
    ]
}

Possible message types are email, in_app_message, android_push, apple_push, kindle_push, windows_phone8_push, and windows_universal_push. All push message types will have the same statistics shown for android_push above.

Campaign Details Endpoint

This endpoint allows you to retrieve relevant information on the campaign, which can be identified by the campaign_id.

GET https://api.appboy.com/campaigns/details

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
campaign_id Yes String Campaign Identifier

Note: The campaign_id for API campaigns can be found on the Developer Console page and the campaign details page within your dashboard or you can use the Campaign List Endpoint.

Example URL: https://api.appboy.com/campaigns/details?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&campaign_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Campaign Details Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "created_at" : (string) date created as ISO 8601 date,
    "updated_at" : (string) date last updated as ISO 8601 date,
    "name" : (string) campaign name,
    "schedule_type" : (string) type of scheduling action,
    "channels" : (array) list of channels to send via,
    "first_sent" : (string) date and hour of first sent as ISO 8601 date,
    "last_sent" : (string) date and hour of last sent as ISO 8601 date,
    "tags" : (array) tag names associated with the campaign
}

News Feed Export

News Feed List Endpoint

This endpoint allows you to export a list of news feed cards, each of which will include it’s name and Card Identifier. The cards are returned in groups of 100 sorted by time of creation, most recent first.

GET https://api.appboy.com/feed/list

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
page No Integer The page of cards to return, defaults to 0 (returns the first set of up to 100)
include_archived No Boolean Whether or not to include archived cards, defaults to false

Example URL: https://api.appboy.com/feed/list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1&include_archived=true

News Feed List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "cards" : [
        {
            "id" : (string) Card Identifier,
            "type" : (string) type of the card - NewsItem (classic cards), CaptionedImage, Banner or DevPick (cross-promotional cards),
            "title" : (string) title of the card,
            "tags" : (array) tag names associated with the card
        },
        ...
    ]
}

News Feed Analytics Endpoint

This endpoint allows you to retrieve a daily series of engagement stats for a card over time.

GET https://api.appboy.com/feed/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
card_id Yes String Card Identifier
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request

Note: The card_id for a given card can be found the Developer Console page and on the card details page within your dashboard or you can use the News Feed List Endpoint.

Example URL: https://api.appboy.com/feed/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&card_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00

News Feed Analytics Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "clicks" : (int) ,
            "impressions" : (int),
            "unique_clicks" : (int),
            "unique_impressions" : (int)
        },
        ...
    ]
}

News Feed Details Endpoint

This endpoint allows you to retrieve relevant information on the card, which can be identified by the card_id.

GET https://api.appboy.com/feed/details

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
card_id Yes String Card Identifier

Note: The card_id for a given card can be found the Developer Console page and on the card details page within your dashboard or you can use the News Feed List Endpoint.

Example URL: https://api.appboy.com/feed/details?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&card_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

News Feed Details Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "created_at" : "2015-08-10T15:19:03-04:00",
    "updated_at" : "2015-08-11T15:19:03-04:00",
    "name" : "Sale Card 2015",
    "publish_at" : "2015-08-15T15:19:03-04:00",
    "end_at" : "2015-08-18T15:19:03-04:00",
    "tags" : (array) tag names associated with the card,
    "title" : "News Flash!"
    "image_url" : "https://www.appboy-images.com/foo.png",
    "extras" : { "kvp" => "value" },
    "description" : "Today get 20% off!"
}

KPI Export

Monthly Active Users Endpoint

This endpoint allows you to retrieve a daily series of the total number of unique active users over a 30 day rolling window.

GET https://api.appboy.com/kpi/mau/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier; if excluded, results for all apps in app group will be returned

Example URL: https://api.appboy.com/kpi/mau/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=7&ending_at=2014-12-10T23:59:59-05:00

Monthly Active Users Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "mau" : (int)
        },
        ...
    ]
}

Daily Active Users Endpoint

This endpoint allows you to retrieve a daily series of the total number of unique active users on each date.

GET https://api.appboy.com/kpi/dau/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier; if excluded, results for all apps in app group will be returned

Example URL: https://api.appboy.com/kpi/dau/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=7&ending_at=2014-12-10T23:59:59-05:00

Daily Active Users Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "dau" : (int)
        },
        ...
    ]
}

New Users Endpoint

This endpoint allows you to retrieve a daily series of the total number of new users on each date.

GET https://api.appboy.com/kpi/new_users/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier; if excluded, results for all apps in app group will be returned

Example URL: https://api.appboy.com/kpi/new_users/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=7&ending_at=2014-12-10T23:59:59-05:00

New Users Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "new_users" : (int)
        },
        ...
    ]
}

Uninstalls Endpoint

This endpoint allows you to retrieve a daily series of the total number of uninstalls on each date.

GET https://api.appboy.com/kpi/uninstalls/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group API Identifier
length Yes Integer Max number of days before ending_at to include in the returned series - must be between 1 and 100 inclusive
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App API Identifier; if excluded, results for all apps in app group will be returned

Example URL: https://api.appboy.com/kpi/uninstalls/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=7&ending_at=2014-12-10T23:59:59-05:00

Uninstalls Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) date as ISO 8601 date,
            "uninstalls" : (int)
        },
        ...
    ]
}

Sessions Analytics Export

Sessions Series Endpoint

This endpoint allows you to retrieve a series of the number of sessions for your app over a designated time period.

GET https://api.appboy.com/sessions/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App Identifier retrieved from the Developer Console to limit analytics to a specific app
segment_id No String Segment Identifier indicating the analytics enabled segment for which sessions should be returned

Example URL: https://api.appboy.com/sessions/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Sessions Series Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "sessions" : (int)
        },
        ...
    ]
}

Custom Events Analytics Export

Custom Events List Endpoint

This endpoint allows you to export a list of custom events that have been recorded for your app. The event names are returned in groups of 250, sorted alphabetically.

GET https://api.appboy.com/events/list

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
page No Integer The page of event names to return, defaults to 0 (returns the first set of up to 250)

Example URL: https://api.appboy.com/events/list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1

Custom Events List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "events" : [
        "Event A",
        "Event B",
        "Event C",
        ...
    ]
}

Custom Events Series Endpoint

This endpoint allows you to retrieve a series of the number of occurrences of a custom event in your app over a designated time period.

GET https://api.appboy.com/events/data_series

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
event Yes String The name of the custom event for which to return analytics
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App Identifier retrieved from the Developer Console to limit analytics to a specific app
segment_id No String Segment Identifier indicating the analytics enabled segment for which event analytics should be returned

Example URL: https://api.appboy.com/events/data_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&event=Event%20A&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Custom Events Series Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "count" : (int)
        },
        ...
    ]
}

Revenue Analytics Export

Products List Endpoint

This endpoint allows you to export a list of products that have been purchased in your app. The product names are returned in groups of 250, sorted alphabetically.

GET https://api.appboy.com/purchases/product_list

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
page No Integer The page of product names to return, defaults to 0 (returns the first set of up to 250)

Example URL: https://api.appboy.com/purchases/product_list?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&page=1

Products List Endpoint API Response:

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "products" : [
        "Product A",
        "Product B",
        "Product C",
        ...
    ]
}

Revenue Series Endpoint

This endpoint allows you to retrieve a series of the money spent in your app over a designated time period.

GET https://api.appboy.com/purchases/revenue_series

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
product No String The name of the product to which revenue numbers should be limited (defaults to total revenue across all products)
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App Identifier retrieved from the Developer Console to limit analytics to a specific app

Example URL: https://api.appboy.com/purchases/revenue_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&product=Product%20A&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Revenue Series Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "revenue" : (float) revenue in USD
        },
        ...
    ]
}

Purchase Quantity Series Endpoint

This endpoint allows you to retrieve a series of the number of purchases made in your app over a designated time period.

GET https://api.appboy.com/purchases/quantity_series

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
length Yes Integer Max number of units (days or hours) before ending_at to include in the returned series - must be between 1 and 100 inclusive
product No String The name of the product to which purchase numbers should be limited (defaults to total purchases across all products)
unit No String Unit of time between data points - can be “day” or “hour” (defaults to “day”)
ending_at No DateTime (ISO 8601 string) Point in time when the data series should end - defaults to time of the request
app_id No String App Identifier retrieved from the Developer Console to limit analytics to a specific app

Example URL: https://api.appboy.com/purchases/quantity_series?app_group_id=75480f9a-4db8-4057-8b7e-4d59bfd73709&product=Product%20A&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id=3bbc4555-8fa0-4c9b-a5c0-4505edf3e064

Purchase Quantity Series Endpoint API Response

Content-Type: application/json
{
    "message": (required, string) the status of the export, returns 'success' when completed without errors,
    "data" : [
        {
            "time" : (string) point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
            "purchase_quantity" : (int)
        },
        ...
    ]
}

Fatal Error Response Codes

The following status codes and associated error messages will be returned if your request encounters a fatal error. Any of these error codes indicate that no data will be processed.

Error Code Reason / Cause
400 Bad Request Bad Syntax
401 Unauthorized Unknown or missing app group id
429 Rate Limited Over rate limit
5XX Internal server error, you should retry with exponential backoff

Raw Event Stream Export

Appboy allows you to export the entire raw event stream of data from your application. The export will consist of a series of zipped CSV files of events and event properties. These CSV files contain both the information sent by your application (such as custom events and purchases) as well as data automatically collected and logged by Appboy (such as session starts and ends, news feed card impressions, email and push opens, campaign conversions, etc.).

In order to use the raw data export, you must have your Amazon S3 credentials linked to Appboy. Data will be uploaded to your S3 bucket with object keys matching the patterns “appboy-event-data/app_groups/APP_GROUP_ID/YYYY-mm-dd-HH-MM-events.csv.zip” and “appboy-event-data/app_groups/APP_GROUP_ID/YYYY-mm-dd-HH-MM-event_properties.csv.zip”. Depending on the time interval you have selected, there may be multiple files included in the export. If you specify an output_format of gzip, then the file extension will be .gz instead of .zip.

POST https://api.appboy.com/raw_data/export

Parameter Required Data Type Description
app_group_id Yes String App Group Identifier
app_ids No Array App Identifiers retrieved from the Developer Console. Use the app_id “api” for events from the REST API. When set, the export will be limited to these specific apps, otherwise all data will be exported
starting_at Yes DateTime (ISO 8601 string) Point in time in which the data export should begin
ending_at Yes DateTime (ISO 8601 string) Point in time in which the data export should end
callback_endpoint No String Endpoint URL Appboy will hit once the export has finished
event_names No Array of Strings Array of event names to export (i.e., custom event names or Appboy Event Names); when set, only these events will be exported
output_format No String The file format that will be used for output files. Allowed values are “zip” or “gzip”. Unrecognized output formats will export as zip files.

Example Event Export CURL

The following example CURL demonstrates how to export events via the Appboy APIs. Campaign Recieved and Email Opened are used as example events, but you can include anything from this list or any custom event. You can also omit the array if you want everything.

curl -X POST -H "Content-Type: application/json" -d '{"app_group_id":"YOUR_APP_GROUP_ID","starting_at":"2016-02-23T22:49:05+00:00","ending_at":"2016-02-23T23:49:05+00:00","event_names": ["$campaign_received", "$email_opened"]}'

Raw Event Stream Endpoint API Response

Content-Type: application/json
{
    "success":true,
    "message":"success"
}

Please be aware of the following limitations to this endpoint:

  • The raw event stream export is not available to those on the EU data center.
  • You can only have one raw data export going on at any point in time. If you post multiple requests while a data export is in progress, Appboy will return a 429 error code indicating that you have hit your rate limit.
  • You may only export up to one week’s worth of data at a time. If you wish to export larger time periods, wait for the first export to finish before triggering the next export time period. We recommend making use of the callback_endpoint parameter in order to automate larger exports.
  • The data exported in this endpoint is delayed by 24 to 48 hours. All other endpoints return data in realtime except for this endpoint.
  • You can only export data from the last 3 months.
  • We will show a $campaign_received event for each message type a user received from a single campaign. For example, if a user receives a push notification, an in-app message, and an email from a single campaign, they will have three total $campaign_received events reported. Each of those events will have a different message variation ID recorded in the event_properties table.

Appboy Event Names

The below events correspond to internal events generated by Appboy, and are potential values to be set in the event_names optional parameter.

Event Name Description
$session_started Session started
$session_ended Session ended
$iap Purchase
$push_opened Push Notification Direct Open
$ios_push_foreground iOS Push Notification Received While App Was Foregrounded
$in_app_message_impression In-App Messaging Impression
$in_app_message_clicked In-App Messaging Clicked
$slideup_impression Original In-App Messaging Impression
$slideup_clicked Original In-App Messaging Click
$campaign_received Campaign Received by User, one event will be logged per channel
$canvas_entry User Enters Canvas
$canvas_step_received Canvas Step Received by User, one event will be logged per channel
$card_clicked News Feed Click
$card_impression News Feed Impression
$email_opened Email Open
$email_clicked Email Click
$email_unsubscribed User Unsubscribes From Email
$email_bounced Email Address Bounces
$first_used_app User Uses App For the First Time
$campaign_converted User Converts From Campaign
$canvas_converted User Converts From Canvas
$news_feed_viewed Appboy News Feed Is Viewed
$attribution_data_received Install Attribution From Source
$uninstalled User Uninstall Detected

API Campaigns

Campaigns sent through the Messaging API can have the same detailed reporting and retargeting options as campaigns created on the dashboard. This section of the documentation will detail how to generate a campaign_id to include in your API calls and take advantage of this feature.

Step 1: Click “API Campaigns” on the “Campaigns” page

Navigate to the Appboy Campaigns page in your company dashboard and click “Create Campaign” then click “API Campaigns”

API Campaigns

Step 2: Configuring API Campaigns

  1. Add a descriptive title so you can find the results on our campaigns page after you’ve sent your messages.
  2. Click the “Add Message” button and add the messages types which will be included in your API campaign.
  3. Optionally add a conversion event to track user conversions on a specific action or campaign goal.
  4. Click “Save Campaign” and you’re set to begin your API campaign.
  5. Include the generated campaign_ID fields with your API request where noted in the Messaging API - Send Endpoint Spec

Configuring API Campaigns

API Connectivity Issues

Appboy’s API endpoint use a CDN that routes traffic to the closes POP based on DNS information. If you are having issues connecting or notice that you are connecting to a POP that is not efficient please make sure to use your providers DNS servers or DNS servers that are setup in the same data center as your server and have proper IP location meta information associated with them.

We have noticed that a handful of firewalls attempt to modify or secure HTTPS/TLS traffic which interferes with connections to Appboy’s API endpoint. If your servers are behind any sort of physical firewall please disable any HTTPS/TLS acceleration or modifications that the firewall(s) and/or router(s) are performing. Additionally you can whitelist outbound traffic to our CDN providers (Fastly.com) to see if that resolves the issue.

Occasionally iptables setups that filter on syn/ack/rst packets can also cause issues, so if you are using iptables on your host you could also whitelist outbound traffic to our CDN providers (Fastly.com) to see if that resolves the issue.

If you are still having network issues with connecting to Appboy’s API Endpoint please provide a MTR MTR Test and the results from Fastly Debug while experiencing an issue and submit that with your support request.
The test results must be obtained from a server that is having issues connecting to Appboy’s API endpoint and not from a development laptop. A network capture (tcpdump or pcap file) will also be helpful if it can be obtained.

Whitelisting Appboy’s API Endpoint IP Ranges

To whitelist Appboy’s API endpoint through your firewall, our CDN provides access to the list of assigned IP ranges via a JSON dump. You can access that list via URL