Syncing Database Changes from MailChimp to You:

In this scenario, you already have a database or list. You want to collect some or all of the information associated with your subscribers, preferably as it changes, and save it back to your database.

What might you do with that information? Here are some options:

  1. If you rely on having valid email addresses for your customers, you'll definitely want to get bounce and unsubscribe data.
  2. You may have important information in our merge fields or interest groups that your systems rely on.
  3. You want to know about new subscribers quickly and without parsing out emails.

Before continuing, you'll need to get a few things out of the way:

Next Steps

Please keep in mind that we strongly discourage the practice of simply pulling your entire list, cycling though every user, and pulling down their details as a method of syncing up with us. However we do understand that there are time that is necessary and that is exactly why we provide the Export API. Keep reading to learn how to implement a smart and scalable solution.

One of our most requested functions is a way to capture subscribes, unsubscribes, and profile updates in real time. We support two standard and durable methods for syncing data, and we've documented two other methods that can be useful for performing syncs via the API.

Webhooks

Webhooks allow you to subscribe to various events occurring in our systems, and have your systems receive notifications about them in near real time. We've documented them separately.

API Time/Delta-based Syncs

As of the v1.2 release of our API, we support some much smarter, more durable methods for obtaining only the updated data that you need via the API—just keep an eye out for the since parameters.

Keeping a List Synced

Keeping an internal database/list synced with your MailChimp list is the type of synchronization that users are most interested in. After our v1.2 and later releases of our API, we support an additional since parameter for the listMembers method. Using that parameter, you can simply request all changes for a particular status since a certain date and time, which typically would be the last time you ran your sync scripts. We also added an additional status, updated. Here's a recap of the statuses:

  • subscribed - retrieve all subscribed users since a particular date/time
  • unsubscribed - retrieve all users who have unsubscribed since a particular date/time
  • cleaned - retrieve all cleaned users since a particular date/time
  • updated - retrieve all users who have updated their profile data since a particular date/time

There are two caveats if you're only using the API sync methods:

  1. Times for status changes for all items can come via a subscriber manually using your forms, an admin user logged in to our web interface, list imports, and even API calls and updates. If you want more granular control, consider using our Webhooks in addition to or instead of these methods.
  2. Changes to emails will not be easy to see. They'll appear in the updated status list. To be sure you capture these, consider using our Webhooks as well.

Keeping Stats and Reports Synced

Some organizations like to pull in stats and reports from their campaigns and lists to do fun things with them internally. We now have a few extra API methods and updates to help you keep up with these tasks:

  • campaigns() allows you to simply pass in a specific campaign ID to get details, rather than having to do a search.
  • Our Campaign Stats Methods give you access to all the stats and reports we have on your campaign.
  • Our Campaign AIM Methods let you get at the real hairy details of everything that happened.

Faking a Callback

Note:   You must switch your forms to advanced customization mode to use this. Sometimes we call this the fake image hack. Here's how it works.

For each item that should be captured, start by editing the "finished" form for each:

  • Log into the MailChimp Web app
  • Select the appropriate list
  • Click Design signup forms & response emails.

Here are the forms you’ll be editing:

Data to Track Form to Edit
SubscribesConfirmation "Thank You" Page
UnsubscribesUnsubscribe Success Page
Profile UpdatesUpdate Profile "Thank You" Page

You're going to stick a fake image tag and some merge tags in the URL, probably near the bottom of the page and out of the way. Here are a few examples:

<img src="http://www.example.org/sub?email=*|B64EMAIL|*" height="1" width="1">

<img src="http://www.example.org/unsub?email=*|B64EMAIL|*"> height="1" width="1">

<img src="http://www.example.org/profile?email=*|B64EMAIL|*"> height="1" width="1">

Depending on what you need, you can use any merge tags you have created, or even our unique email ids (*|UNIQID|*) when creating that URL.

Next, on your server, you'll need to create the scripts that will read in the variables, and update your systems appropriately. It's not necessary, but we strongly suggest returning valid image data, just to be sure it display correctly in all browsers. Some will ignore the tag if there's a non-valid image, others (like IE) may place a nasty placeholder in your form. Of course that image can (and probably should) be incredibly small and blank, so the user doesn't even notice it.

To summarize, placing that image tag makes a request back to your server. Sure, it's a little hacky, but you know what? It works! In fact, many systems use the exact same method—even our open tracking in your campaigns does this.

Finally, you might want to consider adding some logic on your side to handle the inevitable case where a user accidentally hits a page repeatedly, and you don't want to keep making changes on your system.

Meta Redirects

Note:   You must switch your forms to advanced customization mode to use this!
Meta redirects are simple and usually obvious. They also require the most effort on your side. Basically, you're going to edit your start form this way:

  • Log into the MailChimp Web app
  • Select the appropriate list
  • Click Design signup forms and response emails.

Here are the forms that you'll be editing:

Data to TrackForm to Edit
SubscribesSignup Form
Profile UpdatesUpdate Profile Form

The one complaint we hear with this method is that slow connections may see some of the page load before their browser actually does the redirect. Our best advice is to remove, comment, and hide as much as possible on the page, and put the redirect at the very top. If you're not familiar with meta redirects, here's some documentation. Basically, you'll place a tag like one of these:

<meta http-equiv="refresh" content="0;URL=http://www.example.org/sub">

<meta http-equiv="refresh" content="0;URL=http://www.example.org/profile?email=*|EMAIL|*">

Then you have them on your site, and you have their email address. At this point, you'll be responsible for replicating those forms and submitting the appropriate API call to us.