POST - Set Email Subscription
The Email Subscription API allows you to:
- Add and remove email addresses from a user profile. The profile will automatically be created if needed.
- Edit a profile's marketing subscription.
- Set a timezone on a profile.
- Set a custom language or region on a profile.
This will be moved to another API in a future release.
Projects and Profiles
Before we begin, we would like to talk about two new paradigms that we introduced on the Batch platform for Emails.
Projects group Android/iOS apps, Websites and Emailing together in a single entity. Projects have their own API key for use with our new APIs.
Data used to be siloed between different apps: projects remove that limitation by introducting profiles.
Profiles centralize data and events from multiple sources (Apps, Websites, APIs) in a single place based on the Custom user ID. They can also store a profile's email and email subscriptions.
This allows Batch to support more complex and cross-channel lifecycles: it is now possible to message a user on a channel even though its profile data is fed from another one.
For example, this use case is now supported:
- A user creates an account from your Android app. You use the Android SDK to set a Custom User ID and add Custom Attributes.
- You collect their email and use the Email Subscription API to tell Batch about it.
- This user then logs in on your website, which sets the Custom User ID.
- The user performs some action on your website, which you send to Batch using the Custom Events
You will now be able to create an email automation campaign, which automatically uses the data from the Android app and reacts to events the user did on your website thanks to the Custom User ID.
Request structure
Route
The Email Subscription API exposes two POST endpoints:
https://api.batch.com/2.0-alpha/BATCH_PROJECT_API_KEY/profile/CUSTOM_USER_ID/emailfor single-profile operationshttps://api.batch.com/2.0-alpha/BATCH_PROJECT_API_KEY/profiles/emailsfor bulk updates, up to 10000 operations
Headers
In order to authenticate with the API, you need to provide your company REST API Key as the value of the X-Authorization header. You can find it in ⚙ Settings → General.
Insufficient privileges issue: You may see that error in the REST API key field. This happens because the REST API key is only visible to managers. Make sure the managers of the account share that key with you or ask them to grant you access through the team manager.
API Description
This API schema is available in the OpenAPI 3.0 format: View it online.