On this page, you’ll find a guide through our API Version 2 by use cases. We try to answer the most common questions on how to integrate external systems with the Newsletter plugin using our REST API 2. The REST API 1 is still active and supported but they’re less complete and flexible, so we suggest migrating as soon as you have the opportunity to review your integration.
Both API version 1 and version 2 are supported by installing a free addon.
Free add-ons can be downloaded from your account page.
API Reference
You can look at the full API reference documentation to get every detail.
Authentication
Most API calls need an authentication key to be invoked.
I want to add a subscriber to my blog when it is added to my CRM (or similar tool)
For this task, you should use the subscribers endpoint with the POST method. It accepts a JSON object in the request body containing the subscriber data (the email address is the only required field). You can even set private lists and private profile fields.
This method requires an authentication key to be called and must never be used from a public client but only for server-to-server data exchange.
This method does only simple data cleanup and usually ends with an error only if the email address is not valid. No spam check is made since it is assumed the data provider by your other system is already correct.
This endpoint returns an error if the subscriber is already present without changing it. So you can use it only to add new subscribers.
It does not send activation or welcome emails, simply inserts the subscriber in the database (and returns all subscriber data together with its assigned ID). It is even assumed you have collected the consent to treat that data.
About the subscriber status
The subscriber status determines if she can receive or not your newsletters. Since the data is provided by an external system if the status is not indicated it is set to “confirmed” and it means newsletters can be sent to those subscribers. If a different status should be set, it must be provided with the request data.
I want to update an existing subscriber with new data I collected elsewhere
Use the subscribers endpoint with the PUT method, along with the ID or the email. This endpoint accepts any kind of subscriber data field and overwrites the current data stored in the blog.
There are two options to match the subscriber to be updated. You can provide an email address or you can provide the Newsletter subscriber ID. You can even update the associated email address stating that the new email address is not already registered for a second subscriber (otherwise you’ll get back an error).
Subscriber fields that are not provided with the request are left with the original value (or their default empty value when the subscriber is created as new). Hence this operation is limited only to the provided fields and can be used to make even specific changes.
This method is allowed to update even private lists and profile fields and it requires an authentication key and must never used in a public client: it is meant to be used only by server-to-server exchanges.
I want to add or update a subscriber in a single call
Use the PUT method of the subscribers endpoint as per the example above.
I want to set the subscriber as bounced/unsubscribed/…
Actually, this is a subscriber status change. It can be accomplished with PUT method providing a subscriber ID or the email address and, of course, the new status.
If an email address is provided and it is not already present in the Newsletter plugin database a new subscriber is added with the provided status.
A direct status change does not fire events (email sending or like).
I want to add a subscriber to a specific list or lists
That happens usually when something externally happens, for example, the subscriber takes some actions like subscribing to a specific service.
The PUT method of the subscribers endpoint can be used. You need to provide a subscriber ID or an email address and the list or lists you want to change. A list can be added to a subscriber setting it to 1 or removed from a subscriber setting it to 0.
Interaction with the Autoresponder addon
If a subscriber is added to a list connected to an Autoresponder, she’ll start to receive the email series. The actual link between the subscriber and the email series is processed within 5 minutes. Hence, if your series has the first step with delay set to zero, the first email is sent within 5 minutes, not immediately.
I want to delete (completely) a subscriber
The DELETE method of the subscribers endpoint can be used. The deletion is a full and unrecoverable removal of all subscriber’s data. Not only the personal data but even all statistics data, like the interaction with newsletters and so on.
No trace of that subscriber should be found after a deletion request.
This method requires an authentication key to be called and must never be used from a public client but only for server-to-server data exchange.
About deletion and cancellation (unsubscription)
If you want to unsubscribe a subscriber retaining all her data but blocking Newsletter to send her, the correct operation is a status change to unsubscribed (see the example above). Pay attention, they are pretty different actions!
I want to start the standard subscription process
This API endpoint can be triggered even from public clients and does not requires an API key. It is meant to be a service to support subscriptions started in different ways that a standard form, for example from an app.
The endpoint is subscriptions with the POST method. The minimum required information is an email address.
This operation is really different from the action of adding a subscriber since it starts the whole subscription process with spam check, duplication check, activation, or welcome email sending (it depends on the opt-in mode configured).
Some options to control the subscription process are available (see the reference) and they can overwrite the defaults set on Newsletter administration panels.
I want to start a cancellation process
This is actually not available with pur API. The subscriber can start a cancellation process following the cancellation link you should provide in each newsletter.
You can anyway change the subscriber status with a server-to-server call using the subscribers endpoint.
Attention: the subscribers endpoint must never be used from a public client, since it requires an API key which must be kept private.
That is going to be updated on future releases allowing public calls with subscriber level authorization tokens.
I want to make a public service where the subscriber can change her profile data
This is actually not possible with the API in a public client-to-server fashion. You can implement service at the server level and use the subscribers endpoint and related methods.
Attention: the subscribers endpoint must never be used from a public client since it requires an API key which must be kept private.
That is going to be updated on future releases allowing public calls with subscriber-level authorization tokens.
I want to get the configured subscription lists
The endpoint to use is lists and the method GET. It returns all lists configured (public and private) when invoked with an API key.
I need a list of the last newsletters sent
The specific endpoint newsletters can be used to get back the last newsletters completely sent. Since a newsletter can be set as private, you need to use an API key to get them all, otherwise only the public ones are returned.
By default, you get the last 10 newsletters. This service can be used to create an archive (pagination is available, see the reference).
Sending, paused, draft or future planned newsletters are not returned.
I want to test the API on localhost without HTTPS
To test the API on the server without HTTPS protocol, add this code in the wp-config.php file:
define ('NEWSLETTER_REST_ALLOW_NON_HTTPS_REQUEST', true);Please note that this change will allow API calls without HTTPS, so the security keys will not be encrypted from client to server.