Push REST API

6 min

You can use the Push REST API to add recipients for the mobile push channel to Optimizely Campaign. This API processes HTTP-POST requests. For general information about sending push messages with Optimizely Campaign, see the article Overview.

Endpoint and Request Structure

The base URL for all requests is http://push-api.broadmail.de/rest/push

Requests consist of:

the base URL,

a method part,

and a query parameter called authenticationToken.

Here is an example of a request-url:

curl --header 'Content-Type: application/json' --data '{"packageName": "a123", "registrationToken": "r123"}' <http://push-api.broadmail.de/rest/push/register/v2?authenticationToken=><my-auth-token>

(replace <my-auth-token> with the authentication token)

Parameters

All requests contain the authentication token, that authorizes the request. Additionally, HTTP-POST-Parameters may be specified. They are accepted in JSON format. Therefore the HTTP-Post-Header should contain the following header field:

Name	Value
Content-type	application/json

Methods

/register

Creates or updates a recipient. This methods supports only pure push recipient lists where the push registration token is the primary key and push is the only channel. For multi-channel recipient lists or for lists where the push registration token is not the primary key, you can use_ /register/v2_ instead.

The /register method has following POST parameters:

Name	Type	Required	Description
packageName	String	✓	The package name of the app as configured by Optimizely support. It is mapped to the recipient list used for the registration.
registrationToken	String	✓	The registration token that will be inserted into the recipient list.
oldRegistrationToken	String		Optional old registration token, that will be searched for to be replaced with the new registration token.

/register/v2

Creates or updates a recipient. Supports multi-channel lists with more than one address field and lists where the registration token is not the primary key.

The /register/v2 method has following POST parameters:

Name	Type	Required	Description
packageName	String	✓	The package name of the app as configured by Optimizely support. It is mapped to the recipient list used for the registration.
recipientId	String	✓	The recipientId references the primary key of the recipient list, which may or may not be the push token. If recipientId is empty, nothing will happen. Else the recipient will either be newly created or updated (see oldRecipientId).
oldRecipientId	String		Optional old recipient ID. If a recipient with the oldRecipientId exists, its primary key will be changed to recipientId.
additionalRecipientData	Map<String, String>		A map from recipient list field name to value that will be used to update the recipient list entry for the recipient. bm_token is used as a special key here and denotes the push registration token.

Example: curl --header "Content-Type: application/json" --data '{"packageName": "de.optimizely.example", "recipientId": "[[email protected]](mailto:[email protected])", "additionalRecipientData": {"bm_token": "my-registration-token", "firstname": "Max", "lastname": "Mustermann"}}' <http://push-api.broadmail.de/rest/push/register/v2?authenticationToken=><my-auth-token>

(replace <my-auth-token> with the authentication token)

/unregister

Searches for all recipients with the given registration token and performs one of the following actions:

If the registration token is the primary key or if mobile push is the only channel of the recipient list or if the registration token is configured to be required, the recipient is completely deleted from the recipient.

Else, only the registration token is removed (emptied) from the recipient that matches the specified registration token and the recipient remains in the list.

The /unregister method has following POST parameters:

Name	Type	Required	Description
packageName	String	✓	The package name of the app as configured by Optimizely support. It is mapped to the recipient list used for this request.
registrationToken	String	✓	The registration token, that will be removed from the recipient list.

Example: curl --header 'Content-Type: application/json' --data '{"packageName": "de.optimizely.example", "registrationToken": "my-registration-token"}' <http://push-api.broadmail.de/rest/push/unregister?authenticationToken=><my-auth-token>

(replace <my-auth-token> with the authentication token)