Mailchimp CiviCRM Sync 1.1

published on Friday, 06 July 2012 12:24

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 +
  • Drupal 6.x and CiviCRM 3.4.x +
  • Joomla 1.6+ and CiviCRM 4.0 +
  • Drupal 7.x and CiviCRM 4.0 +
  • Wordpress and CiviCRM 4.1.3 +
 
The script has been tested on al versions of CiviCRM as far as 4.1.3.
 

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
 
Version 1.1 Alpha has been optimised to increase speed and efficiency of the synchronisation.  This version also increases the overall security of the script, and the logging feature has been improved, making easier to see exactly what the script has synchronised.  The new version of the script also works with CiviCRM that is running in Wordpress.

Setting Up Sync in CiviCRM

The following instructions are suitable for both Joomla, Drupal and Wordpress 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.

Configuring the Script

In order for the script to communicate with your MailChimp account, it needs an API key for your account, the ID of the list you wish you synchronize to, the url of the script.

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";

Once you have added the API key to the script, you will also need to add th eList ID. To do this, go to your Mailchimp Dashboard, click on 'Lists' from the menu bar, and then go to 'Settings' > 'List Setting and Unique ID' in the section of the list you wish to synchronize to.  The Uniquer ID for the List is available at the bottom of the page, copy this and paste it into the scrit where it says: $this->apikey, like this:

$this->list_id = '123456789';

You will also need to add in the base url of the script.  Although the script cannot be run through a browser (you will get an error message if you try to), it can be pinged by Mailchimp, which is required for it to run properly.

Your base URL will look something like this:

  • $this->config->base_url = 'http://www.example.com/administrator/components/com_civicrm/civicrm/bin/mailchimp_sync.php';
  • $this->config->base_url = 'http://www.example.com/sites/all/modules/civicrm/bin/mailchimp_sync.php';
  • $this->config->base_url = 'http://www.exampe.com/wp-content/plugins/civicrm/civicrm/bin/mailchimp_sync.php';

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

Wordpress:
/wp-content/plugins/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 php /path/to/civicrm/bin/mailchimp_sync.php > mailchimp_log.txt

where "/path/to/civicrm" is the url of your mailchimp script. For example 'var/www/sites/all/modules/civicrm/civicrm/bin/mailchimp_sync.php'. The above will create a daily cron job. You may change the schedule depending on how often you want the changes to be synchronised between CiviCRM and MailChimp, however, it is highly recommended that the script not be run more than a couple of times a day, especially for systems with a large number of contacts.  

The cron command above stores the output of the sync script in a file called mailchimp_log.txt, which is overwritten every time the script runs.  If the script does have permissions to create this file then you will have to create it and make sure the script has permissions to write to it.

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:\PHP5\php.exe -f "C:\Inetpub\sites\all\modules\civicrm\bin\mailchimp_sync.php > mailchimp_log.txt"

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 as a new Interest Grouping, (unless it already exists in MailChimp). This new Mailchimp interesting grouping will have a group called 'default' which is where all the contacts 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 interest groupings on MailChimp, as the mailing list groups they are in CiviCRM, and vice versa. Again, the contacts are added to the 'default' group with the Mailchimp Interest Grouping.
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 for their primary email address, will be unsubscribed from MailChimp mailing lists. Also, any users that un-subscribe 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 that are deleted from CiviCRM, are unsubscribed from MailChimp.
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.

 

When the script runs first it will synchronise all CiviCRM mailing list groups and contacts to Mailchimp.  After this it will only synchronise groups and contacts that have been updated since the last time it ran.  If you wish for some reason to override this behaviour, you can run the sync script manually and add teh the --sync_all command-line parameter.  This will force the script to synchonise all contacts and groups, regardless of whether it thinks they have been updated since the last time it ran, or not.

 

A Note about the Run Key:

The script is designed to be run via the command line.  You will need php-cli installed onn your system in order to do this.  If you try to run the script directly via your browser you will get an error.  This is a security feature that prevents un-authorized access to the script.  Howeveer, the script does need to be able to be run via the web in order for it to take advantage of Mailchimp's webhooks, which allow real-time updating of information from Mailchimp to CiviCRM.  

In order to achieve this, the script uses a run key.  Evey time it runs, it creates a new unique key in your database. When it is run via the command line, it reads the key from the database and then invokes itself via curl, passing the runkey as a parameter.  When the script is run via the web (or via curl) it looks for the runkey parameter, which it compares to the one stored in the database.  If there is a match, the scirpt runs and resets the run key.

If the script is run via the web, and there is no run key, it checks that the requesting service is Mailchimp, and if not, it doesn't run.