Newsletter API Version 2

In 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 are still active and supported but they’re less complete and flexible, so we suggest to migrate as soon as you have the opportunity to review your integration.

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 privare 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 its assigned ID). It is even assumed you have collected the consents to treat that data.

About the subscriber status

The subscriber status affects 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 that 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

User the subscribers endpoint with the PUT method. This endpoint accepts any kind of subscriber data field and to overwrites the current data stored in the blog.

If there is no matching subscriber, a new one is created.

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 use 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.

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. In the latter case, you can even update the associated email address stated that that email address is not already registered for a second subscriber (otherwise you’ll get back an error).

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 subscribe 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 processes 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 a public clients and does not requires and 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 a service at 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 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.

Have you ever considered going premium?

With a premium plan, you'll get whole collection of 30+ professional addons, along with a full year of updates and priority support. No automatic renewals, frequent releases and a solid 30 days refund policy.