In order to interact with this API you will need to read Getting Started with the API.
List email subscribers
GET /publications/{publication_id}/email_subscribers
There are two optional parameters which can be supplied. These should be passed on the query string:
- per_page - How many subscribers to include in the results. The default value for this is 100 and the maximum value is 500.
- page - Which page of data to retrieve. This will be affected by the per_page parameter above.
Subscribe an email
When a subscriber is added using this method they will still receive a welcome email just as if they subscribed using the web site.
Note: This API should only be used to integrate with sites and systems which have made it very clear to the end user that they are going to be subscribed to your list.
POST /publications/{publication_id}/email_subscribers
There is only one required parameter, it should be sent as JSON in the post data:
- email - The email address to subscribe to your list.
By default, adding a subscriber with the API will respect the double opt-in option configured in your settings for your publication. If you want to bypass this setting and automatically add the subscriber without double opt-in, you can pass the following optional parameter. (We always recommend having double opt-in on, but you may want this option if you're syncing your list with another service and the subscriber has already opted in.)
- sync - Default false, can be set to true to bypass double opt-in settings.
Return data
If the subscription was successful, you will receive:
{
"success": true
}
If the subscription failed, you will receive:
{
"success": false,
"error_message": "Unable to subscribe [email protected].",
"errors": [
"Email address is already subscribed."
]
}
Details on why the call failed will be supplied in the error_message parameter as a formatted string including all reasons and also as an array containing a list of errors.
Retrieve an email subscriber
GET /publications/{publication_id}/email_subscribers/{subscriber_id}
There is one parameter and it should be passed as part of the URL.
- subscriber_id - ID of the email subscriber
List email unsubscribers
GET /publications/{publication_id}/email_unsubscribers
There are two optional parameters which can be supplied. These should be passed on the query string:
- per_page - How many subscribers to include in the results. The default value for this is 100 and the maximum value is 500.
- page - Which page of data to retrieve. This will be affected by the per_page parameter above.
Unsubscribe an email
POST /publications/{publication_id}/email_unsubscribers
There is only one required parameter, it should be sent as JSON in the post data:
- email - The email address to unsubscribe to your list.