Overview

Interactive subscriber synchronisation is used when your system needs to use or display up to date information from the Poppulo system. Interactive synchronisation is achieved using the individual subscribers calls. The example we will use is a website for your customers. They have some kind of user account on your website, and they can use this to view, update or remove their subscription to your email newsletters.

Showing a user's details

The first part of this is to display the user's current preferences. Typically, you would want to list a subscriber's email permissions. Remember there is little point pulling a subscriber's name and email address when you have them in your local CRM system. These might be rendered as a checkbox list or multiple select field in a form on the user's profile on your website.

You may also want to read a subscriber's topics. You should avoid reading the subscriber's tags, generally these would not be made visible to subscribers in our system. Tags are easy to create, and could have semi-sensitive names (e.g. someone could create a tag called 'Eager prospects') which might be embarassing if rendered to a subscriber. Our system automatically generates tags during subscriber imports. If you do need to give the subscriber control over some of their tags, we recommend having a whitelist of these tags in your server.

Updating a user's details

Changing a user's subscription

When the user submits this form, you will want to add new permissions, and remove permissions the user has de-selected.

New subscriptions

If the user does not have an associated subscriber in our system, you need to create a new one. When the subscriber has been created, you can begin to add permissions to it. Note that a subscriber is created with the initial status of INACTIVE. They become ACTIVE when a permission is added to them, and can only become INACTIVE again once all permissions have been removed from them.

Unsubscribing and resubcribing users

If the user has indicated they do not wish to receive emails from us any more, you can indicate this by updating the status subscriber entity field. Setting the status to OPT_OUT will remove all permissions the subscriber currently has.

If the user was a subscriber at one point, and now wishes to resubscribe, update their status to INACTIVE or ACTIVE, and add any permissions.

Our system strongly enforces subscriber initiated opt-outs (e.g. clicking "unsubscribe" in a Poppulo email or opting out via a Poppulo Subscribe Box). Please read the section subscriber status for information about this.

Updating user's personal information

If the subscriber changes their email address, or other information that you need available in Poppulo, you can update them with the new data. Note that the order of operations is important here if you are using the subscriber's email to build URIs. If you update the subscribers email, subsequent calls should use the new email address. An alternative to this is to save the subscriber's Poppulo identifier, which doesn't change.

Performance notes

For an efficient integration, we recommend being as conservative as possible, only add or remove the permissions/topics that have been requested, and minimise the number of fields specified when updating the subscriber. Please note that minimising the number of calls is more efficient than minimising the data. To increase your website's responsiveness, consider issuing update/create/delete calls in a background thread or process to avoid blocking the user interface. The result of the calls could be polled with AJAX (e.g. to alert the user of success/failure).

In general, new subscribers are rarer than subscription updates, resubscribing users are rarer than both¹. If you do not store, or cannot infer, whether a subscriber exists or existed in your program then we recommend optimistically assuming that a subscriber already exists. Unconditionally executing a Get Subscriber call would require an extra round trip to our servers. Instead, attempt to update a subscriber, only falling back to creating a new subscriber in the event you get a 404 Not Found error response. Likewise for adding or removing permissions.

---

Footnotes

1. Run your own reports to see what is the normal situation for your users. ↩