The new extension builds on the existing work done by the science gallery, adding the ability to pick the Mailchimp List the CiviCRM group should be integrated to as well as making the entire process a much simpler one to setup.

For each Mailchimp list that you want to integrate, you set up a CiviCRM group. This will control the subscribers in that list. Add contacts to the group in CiviCRM and after pushing the sync button, those will be subscribed to your Mailchimp list. If you remove contacts from the group in CiviCRM, the sync will unsubscribe them at Mailchimp. If anyone clicks an unsubscribe link in a Mailchimp email, they are automatically removed from your CiviCRM group.

Additionally, if you use Mailchimp's "Interest Groupings", you can map particular Mailchimp groups to a CiviCRM group. You can choose whether this is a group that the subscriber can edit (using Mailchimp's forms), or not.

So if you have a list of fundraisers you might use an interest grouping called "Interests" and give subscribers options like "Shaking tins", "Door knocking", "Climbing mountains". Each of these can be mapped to a CiviCRM group (if you so choose) and membership of these groups will be updated.

Alternatively, what if you have groups in CiviCRM like "major donor" or "miserly meanie" that you want to use to segment your mailings but you don't want subscribers seeing or being able to edit these? This is accommodated, too. It's up to you to set up your Mailchimp Interest Groupings so that this fieldset is hidden from subscribers, but then you can just link a CiviCRM group to one of those. These groups will never update from Mailchimp to CiviCRM.

NB Mailchimp sometimes calls Interest Groupings just "Groups", which gets very confusing because you have Groups of Groups, and of course CiviCRM uses the word Group, too! Here I will stick to calling the Mailchimp fields "Interest Groupings" which each contain a number of "Mailchimp Groups", to differentiate them from CiviCRM groups.

1. Download extension from https://github.com/veda-consulting/uk.co.vedaconsulting.mailchimp/releases/latest.
2. Unzip / untar the package and place it in your configured extensions directory.
3. When you reload the Manage Extensions page the new “Mailchimp” extension should be listed with an Install link.
4. Proceed with install.

Before the extension can be used you must set up your API keys...

To get your accounts API you should follow these instructions http://kb.mailchimp.com/accounts/management/about-api-keys

Once you’ve setup your Mailchimp API key it can be added to CiviCRM through "Mailings >> Mailchimp Settings" screen, with url https://<<your_site>>/civicrm/mailchimp/settings?reset=1. Using “Save & Test” button will test that a connection can be made to your Mailchimp account, and if your API settings are correct.

In Mailchimp: Set up an empty list, lets call it Newsletter. You'll also need to set up this list's Webhooks.

Steps to configure Mailchimp Webhook settings with the relevant CiviCRM Url:

1. To know the relevant CiviCRM url visit https://<<your_site>>/civicrm/mailchimp/settings?reset=1.
2. In the “Security Key” field entering a key shows the complete webhook url. Note down the complete url.
3. Make sure webhook url is accessible to public. If not, just make sure anonymous / public user has “allow webhook posts” permission.
4. Log in to your MailChimp account.
5. Navigate to your Lists.
6. Click Webhooks under Settings menu and Click ‘Add a New Webhook’ button.
7. Enter the CiviCRM Webhook URL, noted in #2 ( https://<<your_site>>/civicrm/mailchimp/webhook?reset=1&key=ABCD ) in Callback URL field.
8. Tick the relevant options for type of updates and when to send an update.
9. Click Save.

In CiviCRM: you need a group to track subscribers to your Mailchimp Newsletter List. You can create a new blank group, or choose an existing group (or smart group). The CiviCRM Group's settings page has an additional fieldset called Mailchimp.

Choose the integration option, called "Sync membership of this group with membership of a Mailchimp List" then choose your list name.

Save your group's settings.

The next step is to get CiviCRM and Mailchimp in sync. Which way you do this is important. In our example we have assumed a new, blank Mailchimp list and a populated CiviCRM Group. So we want to do a CiviCRM to Mailchimp Sync. However, if we had set up an empty group in CiviCRM for a pre-existing Mailchimp list, we would want to do a Mailchimp to CiviCRM sync. If you get it wrong you'll end up removing/unsubscribing everyone!

So for our example, with an empty Mailchimp list and a CiviCRM newsletter group with contacts in, you'll find the CiviCRM to Mailchimp Sync function in the Mailings menu.

Push the Sync button and after a while (for a large list/group) you should see a summary screen.

Any un/subscribes from the Mailchimp end will be handled (almost) instantly using the webhook. However changes at the CiviCRM end must be manually sync'd up to Mailchimp, e.g. before you do a new mailing campaign. There are several good reasons why this manual button pressing is necessary, not least that it is how Mailchimp request it be done. Basically there are many ways that CiviCRM group membership can be changed, including bulk updates, and sending a request to Mailchimp for every affected contact would be very slow.

Note: currently, removals are processed as unsubscribes from Mailchimp. This is so that Mailchimp's reporting and subscriber history is not affected by removals. However, Mailchimp treats unsubscribed people in a bit of a permanent way; you cannot ever re-subscribe them! This is caution on Mailchimp's part, as they have to ensure their service is not used by spammers. However it's an awkward feature for the general integration case. The only way to re-subscribe someone who previously unsubscribed is to first delete them from the Mailchimp list.

We have an upcoming feature that will give you the option to force a CiviCRM to Mailchimp sync which will automatically do the necessary deletions, but this is not included in the current version. Watch this space.

For this example we'll set up two interest groupings in Mailchimp, one called Interests that publically viewable, and one called Private that is hidden from subscribers. Within "Interests" add Mailchimp Groups such as "bananas", "organic farming", "climate change activism". Within the "Private" Mailchimp Interest Grouping, you might add Mailchimp Groups called "major donor", "VIPs" etc.

Please take care and follow Mailchimp's help pages for how to restrict the visibility of the Private interest grouping.

Now back in CiviCRM, setup groups to map to these Mailchimp Groups. When you look at the CiviCRM group's settings page, choose "Sync membership with a Mailchimp interest grouping" you'll then see something like:

Here you can see the two options about whether Mailchimp subscribers are supposed to be able to edit their membership of this interest grouping.

So for the Private interest grouping, choose the first, No option, for the public "Interests" one, choose the second option.

Please note that while it's possible to configure one Mailchimp Group to be updatable and another to be non-updatable within the same mailchimp interest grouping, this will lead to unpredictable results. Stick to the rule: if it's public, it should be updateable, if it's hidden/private, it should be not updatable.

When you run the sync, these grouping will be updated accordingly. Nb. a webhook immediately processes changes made from the Mailchimp end.

If you are integrating Mailchimp account that's been there for a while (lots of contacts), with a relatively new CiviCRM setup (less or no contacts), might want to do mailchimp to civicrm sync first (aka pull). Any updates to Mailchimp after that would immediately be handled via webhooks. And updates to CiviCRM could be passed onto Mailchimp via Civi to Mailchimp Sync.

In other words, most Mailchimp changes are handled immediately via webhook. So it is now rare to need the Mailchimp to CiviCRM sync operation, whereas the CiviCRM to Mailchimp sync should become part of your pre-campaign sending preparation.

In any case CiviCRM to Mailchimp sync process can be automated and run on regular basis using the “Mailchimp Sync” scheduled job shipped by extension. The job can be enabled and configured from the Scheduled Job screen: Administer > System Settings > Scheduled Jobs. Note: Users should be aware of possible implications. For example, running a Civi to Mailchimp sync, from an empty civicrm group to a mailchimp list with some data, could unsubscribe / wipe-out all the contacts from mailchimp list.

Version 1.5 and above also ships a scheduled job for "Mailchimp Pull".

Note: Before you do any sync make sure to backup your mailchimp and civicrm contacts.