Our Email Marketing software offers a full featured, easy to use API, with dozens of functions to choose from. Many of our clients have utilized our open API to integration our Email Marketing software with their websites, external databases, and other software applications. Perhaps the most common use of the API is adding new subscribers to the system, and updating existing subscribers.
Whenever you need to add a new subscriber to your system through our API, you must follow these steps:
- Use subscriber_view_email first, to check and see if a subscriber with the same email address already exists.
- If subscriber_view_email returns no response, then use subscriber_add to add a new subscriber.
- If subscriber_view_email does return a response, then save the subscriber data that it returns, and use subscriber_edit to edit the existing subscriber while also retaining their original data (lists, fields, etc).
This blog post will explain how to check to see if a subscriber exists before adding them, and how to update a pre-existing subscriber.
Use subscriber_view_email to Fetch Existing Subscriber Details
Before either adding a new subscriber, or updating an existing subscriber, you must always check to see if that subscriber exists first, and fetch their existing subscriber details. This is extremely important! If you attempt to use the subscriber_add function to add a subscriber who already exists in the system, you will receive an error message telling you that duplicate subscribers cannot be added (unless the “allow duplicate subscriptions” setting is enabled, which is uncommon). Furthermore, if you attempt to update an existing subscriber without fetching their previous information first, you run the risk of accidentally unsubscribing them to previous lists, or losing custom field data.
To check and see if a subscriber already exists in your system, you can use the subscriber_view_email function. This API function only requires that you have the email address of the subscriber, and it will essentially search your database for any record of that email address. If the email address is found, it will return the subscriber ID, name, and all custom fields and lists that the person is subscribed to.
Below is a short example of how you might call the subscriber_view_email function using PHP:
(click to enlarge)
If the email address you are searching for does not exist in your system already, you would receive a response like this:
The result_code would be 0, and the result_message would say “Nothing is returned.” If you receive a response like this from the subscriber_view_email function, then the email address you searched for does not exist in the system, and so it is safe for you to use the subscriber_add function to add them as a new subscriber.
What if the subscriber already exists?
If a subscriber with that email address already exists in your system, the same API call from above would return an array containing all of the subscriber’s data — their subscriber ID number, name, date subscribed, the list(s) they are subscribed to, and all custom field data. This image shows a portion of the array that would be returned:
In this example, a subscriber with the email address “[email protected]” is subscribed to one list, and the list ID number for that list is 2. This can be seen by looking at the “lists” array that is returned within the main array:
(Note: The “listslist” value, also shown in the above image, will include all list ID numbers for the lists the subscriber is subscribed to, separated by a comma.)
If you scroll down a little further in your API result, you will also see that there are two custom fields — Birthday, and City. The subscriber has a Birthday value, but does not have a value for the City custom field:
In this example, we will add this subscriber to a new list (ID number 3), and we will also add a value for the City field. However, because the subscriber already exists in the system, we cannot simply use subscriber_add — we must use subscriber_edit to update them while keeping all of their original data intact (subscriptions, fields, etc).
Updating The Subscriber
Below is a short, simplified code example that can be added under the subscriber_view_email call that was already shown above. This code example will read the array that is returned from the subscriber_view_email call, determine whether or not an existing subscriber was returned, and then determine whether or not to add a new subscriber, or update an existing subscriber.
(click to enlarge)
The above code looks at the result array that was returned from the subscriber_view_email function, and preserves the subscriber’s existing list subscription data, and existing field data. It is very important to always use subscriber_view or subscriber_view_email to look up the subscriber’s existing data before using the subscriber_edit function! Otherwise, you may accidentally erase custom field data, or accidentally unsubscribe the subscriber from their previous lists.
In this example, the subscriber was already present on the list with an ID of 2, and we needed to add them to list 3. If we did not include the foreach loop starting on line 52 — which finds all lists the subscriber was already present on and adds that subscription information to the $post array as well — then the subscriber would have been removed from list 2 when the API call was executed. Similarly, if we did not also include the subscriber’s previous custom field values in the subscriber_edit call, all of their previous custom field values would have been erased.
(Note that the subscriber_add call was not shown in this example, in order to keep the example short. To see a full example of how to use the subscriber_add function, feel free visit our API documentation section of our site.)
When combining the two code examples in this article, and calling the script, you should receive the following result from the susbcriber_edit function, indicating success:
You can perform another subscriber_view_email or subscriber_view (which uses the subscriber’s ID number instead of email address to look them up) call to verify that the list subscriptions and fields were updated properly — or you can view their subscriber details within the application’s administrative interface:
Putting It All Together
If you’d like to copy and paste the full source code used in this example, with comments included, please click here to download the full example script. (However, keep in mind that it is only a simple example — login details, subscriber information, and list and custom field ID numbers will need to be changed to suit your needs!) As always, if you have any questions or comments regarding our API, please do not hesitate to contact our support department, and we would be happy to help!
