Unsubscribe Import API
Purpose
The Nurture Unsubscribe API, in addition to Rokt sending unsubscribes to the client, now allows clients to immediately send unsubscribed users back to the Rokt system for real-time removal of all brand communications.
What are the benefits?
- Efficiency: ensure your email list is up to date 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 consumers.
Sounds great, what do I need to do?
Engage your engineering resources to put the API in place. Please reach out to your account manager for documentation on setting up the API. For those, especially ones who are handling large volumes and for whom nurture lists are a priority, this is well-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, let it take the wheel. Any time a user unsubscribes from Rokt email nurtures or client-direct communications, both systems will be updated automatically in real time.
How do I know this is all working?
Unsubscribed users can be viewed in 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 API key, unique to your account, acting as your credentials to access the Rokt API.
Getting an API Key
- Go to to OP1 - Data for your account
- Click on 'Settings' in the left navigation menu.
- Click on 'Webhook API Key' in the sub-menu under 'Settings'.
- If your account already has an API key, you will 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 which affect your Rokt account, you should treat this API key the way you would treat other credentials like a username and 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 will be unsubscribed. The API will return immediately, but there may be some delay before the unsubscribe is processed. The response body will be a JSON payload containing solely an ID, such as {"id":"de445c4c-ec46-4e86-a945-ca65d59fda32"}*. |
| 400 | You get a 400 Bad Request if there are missing required fields, or your request is in the wrong format. |
*This ID is not particularly meaningful to you but may be useful to assist in troubleshooting if any issues arise, so you may wish at least to write the value to your system's logs.
Since the expected response from the API is a JSON payload, your request should include an "Accept" header of either "/" or "application/json".
Parameters
Exactly ONE of the following keys must be present in the map:
| Parameter | Description |
|---|---|
| A single email address (raw format) |
Command Line Examples
On a Linux or Mac OS 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
Please note that the above examples point to our live production system. So if you test with email addresses like alice@example.com this address would no longer receive nurture emails.
Since this is the Rokt production system, please do not test with any email addresses that you wouldn't want to be unsubscribed.