Nurture Unsubscribe API
Purpose
The Nurture Unsubscribe API allows brands and partners to immediately send unsubscribed customers back to the Rokt system for real-time removal of all brand communications. Additionally, the Nurture Unsubscribe API can be used by Rokt to send unsubscribes to brands.
What are the benefits?
- Efficiency. Ensure your email list is updated in real time.
- Accuracy. Maintain an up-to-date list to ensure only customers who remain opted-in receive your email communications.
Who is the Import Nurture Unsubscribe API suitable for?
- Brands hosting their own unsubscribe landing page (instead of a Rokt-powered landing page).
- Brands simultaneously sending out their own email communications alongside Rokt-powered email nurture series to Rokt-generated customers.
Sounds great. What do I need to do?
Engage your engineering resources to put the API in place. Reach out to your account manager for documentation on setting up the API. For those who are handling large volumes and for whom nurture lists are a priority, this is worth the upfront investment of time.
How does this work once the engineering work is done?
Once the Nurture Unsubscribe API has been set up, you're all set. Any time a customer unsubscribes from Rokt email nurtures or brand communications, both systems are updated in real time.
How do I know it's working?
Unsubscribed customers can be viewed in the Rokt platform under Customer Data > Unsubscribes.
Authorization
The API expects an authorization header as part of the request. This is to ensure that you have permission to access the Rokt platform. The authorization header value should be your account's unique API key, acting as your credentials to access the Rokt API.
Getting an API key
- Go to to OP1 - Data for your account.
- Click Settings in the left navigation.
- Click Webhook API Key in the submenu under Settings.
- If your account already has an API key, you see it on the page. Otherwise, click Create API Key to generate one.
Security note
Since the point of this API key is to enable access to APIs that affect your Rokt account, you should treat this API key the way you would treat other credential (like a password).
API endpoint
| Endpoint URL | https://api.data.rokt.com/1.0/nurture/unsubscribe |
|---|
The API accepts a JSON payload which must be a map. As the payload is JSON, you must set the Content-Type header to application/json.
Response handling
| HTTP status | Description |
|---|---|
| 201 | The email was received and the customer will be unsubscribed. The API returns immediately, but there may be some delay before the unsubscribe is processed. The response body is a JSON payload containing solely an ID, such as {"id":"de445c4c-ec46-4e86-a945-ca65d59fda32"}.This ID is not particularly meaningful to you but may be useful to assist in troubleshooting if any issues arise, so you may want to write the value to your system's logs. |
| 400 | You get a 400 Bad Request if there are missing required fields, or your request is in the wrong format. |
Since the expected response from the API is a JSON payload, your request should include an accept" header of either / or application/json.
Parameters
The following key must be present in the map:
| Parameter | Description |
|---|---|
| A single email address (raw format) |
Command line examples
On a Linux or MacOS X system with the curl command installed, the following command will unsubscribe the email address alice@example.com, assuming that the API_KEY environment variable is set to your API key:
cURL
curl https://api.data.rokt.com/1.0/nurture/unsubscribe --header "Authorization: $API_KEY" --header "Content-Type: application/json" --data '{"email":"alice@example.com"}'
Testing the API
Note that the above examples point to our live production system. So if you test with email addresses like alice@example.com, those addresses would no longer receive nurture emails. Do not test with any email addresses that you wouldn't want to be unsubscribed.