Login to Access Files
Mailchimp CiviCRM Sync 1.1published 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.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:
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.txt
Features and Benefits
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:
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:
Create a Cron Job
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.
Open your systems Task Scheduler (see http://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:
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.