Mailchimp CiviCRM Sync

published on Monday, 16 January 2012 10:27

MailChimp CiviCRM Sync allows you to synchronise the contacts and groups from CiviCRM to MailChimp and vice versa. MailChimp (www.mailchimp.comwww.mailchimp.com) is a Software as a Service which allows you to run email marketing campaigns from an easy to use interface. MailChimp CiviCRM Sync has been tested for:

  • Joomla 1.5.x and CiviCRM 3.4.x
  • Drupal 6.x and CiviCRM 3.4.x
  • Joomla 1.7.x and CiviCRM 4.0.x
  • Drupal 7.x and CiviCRM 4.0.x

Please Note: This script is provided as is without any warranties please make sure your data is backed up before using. This software is released under the GNU / GPL license, for more information, please see: http://www.gnu.org/licenses/gpl-3.0.txthttp://www.gnu.org/licenses/gpl-3.0.txt

Features and Benefits

  • Contact Subscription from MailChimp become contacts in CiviCRM
  • Contacts Unsubscription from MailChimp marks the contact in CiviCRM as "Do Not Email"
  • Contact Removal from a Group or marking it "Do Not Email" in CiviCRM unsubscribes the contact from MailChimp
  • Contact Addition to a group subscribes the contact in MailChimp
  • Only one mailing list is created with Groups same as CiviCRM
  • Uses Cron Job for Synchronisation
  • Uses MailChimp API v1.3

Setting Up Sync in CiviCRM

The following instructions are suitable for both Joomla and Drupal installations of CiviCRM. 

Create your CiviCRM list in Mailchimp

The script only synchronises a list from MailChimp called "CiviCRM". The name of the list is not case senstive. If you already have a list you can either rename it or create a new list and move/copy all the contacts to that list. The groups in CiviCRM will become groups in MailChimp.

Generate MailChimp API Key

To generate a MailChimp api key, log in to MailChimp, choose account > api keys and info, then click on the "Add Key" button.

An api key will be generated and displayed if you already have a key, it will be displayed on this page. Simply copy and past the key into the cron script downloaded from this site.

Store the API key in the Script

In order for the script to communicate with your MailChimp account, it needs an API key for your account.

To do this, edit the mailchimp_sync.php file, and on line 70, enter your api key to replace all zeros.

This is what the line of code looks like before edited:

$this->apikey = (isset($_GET['apikey'])) ? $_GET['apikey'] : "000000000000000000000000000";

Upload the Script to CiviCRM

To install the synchronisation script, copy it to the 'civicrm/bin/' directory, so that the path to the script is:

Drupal:
sites/all/modules/civicrm/bin/mailchimp_sync.php

Joomla:
/administrator/components/com_civicrm/civicrm/bin/mailchimp_sync.php

Create a Cron Job

Linux:

On the command prompt, type:

$ crontab -e

Append the following line to the end of the file:

@daily http://www.yourwebsite.com/path/to/mailchimp_sync.php

where "http://www.yourwebsite.com/path/to/" is the url of your mailchimp script. For example http://www.example.com/sites/all/modules/civicrm/bin/mailchimp_sync.php. The above will create a daily cron job. You may change the schedule depending on how often do you want the changes to be synchronised between CiviCRM and MailChimp.

Windows:

Open your systems Task Scheduler (see http://support.microsoft.com/kb/308569http://support.microsoft.com/kb/308569), and browse to your systems web browser and add the script as a parameter. For example "C:\Program Files\Mozilla Firefox\firefox.exe" http://www.example.com/sites/all/modules/civicrm/bin/mailchimp_sync.php

What happens when the script runs?

The script will run on the specified schedule in Cron Job and will synchronise the following:

1. Adding new group to MailChimp via CiviCRM
Any new group in CiviCRM that is of the type "Mailing List" will be picked up the script and added to MailChimp automatically, (unless it already exists in MailChimp). This new group will have a sub-grouping in MailChimp, called "default", and this is where all the contacts that are in that group will go.
2. Adding contacts to group(s) in MailChimp via CiviCRM
After the script adds CiviCRM groups to MailChimp, it then adds contacts that are in those groups to MailChimp. If the contacts already exist on MailChimp, then the script ensures they are in the same mailing list groups on MailChimp, as the ones they are a part of in CiviCRM, and vice versa.
3. Unsubscribing users from MailChimp/CiviCRM group
In CiviCRM, any user that has the "Do not email" box checked under "Communication Preferences", or the "On Hold" box checked, will be unsubscribed from MailChimp mailing lists. Once this is done, that email address cannot be 're-subscribed' to MailChimp. Also, any users that un-subscrive themselves via MailChimp, will have the "Do not email" flag set in their CiviCRM Communication Preferences.
4. Recording undeliverable emails as a contact activity in CiviCRM.
This will be recorded as an activity in CiviCRM, (of type "email" with a status of "failed"), and will be visible under that contacts "Activities" tab.
5. Recording bulk mailing activity as contact activities in CiviCRM.
Likewise, any emails sent from MailChimp to contacts in a group / mailing list, will have this recorded as an activity under the "Activities" tab.
6. Removing users from MailChimp that are deleted from CiviCRM.
Users thaqt are deleted from CiviCRM, are unsubscribed from MailChimp, (note that they cannot be 're-subscribed' once this is done).
7. Removing contacts from groups in MailChimp that are removed from groups in CiviCRM.
The groups are synchronised, so if a contact is removed from a group in MailChimp, then the contact is also removed from the corresponding group in CiviCRM.
8. Adding users who subscribe on MailChimp as CiviCRM contact
Someone subscribing to your mailing list will be added to CiviCRM as a contact within the corresponding mailing list group that they subscribed to.
9. Updating names of groups on MailChimp that are changed on CiviCRM.
If the name of a group is edited on CiviCRM, it is updated on MailChimp.
10. Updating names of contacts on MailChimp that are changed on CiviCRM.
Likewise, if the name of a contact is edited on CiviCRM, it is updated on MailChimp also.