Apr 12, 2010

Syncing Unsubscribes with Salesforce

Update (6/27/17): A lot has changed over the years! For an updated, comprehensive look at MailChimp for Salesforce, visit our Knowledge Base.

When someone unsubscribes from your mailing list, MailChimp can automatically notify Salesforce to mark the corresponding lead or contact record as having "opted out" of further email communication. That way, you can easily keep your MailChimp and Salesforce data in sync, and MailChimp will empower your customers to manage their own preferences across all your communication channels.

This post will explain the easy steps for setting up a MailChimp "WebHook" that will send the unsubscribe notifications, as well as the Visualforce page that will listen for the notifications and update any relevant Salesforce records.


The techniques described in this article require the following:

  • Salesforce administrator privileges
  • Salesforce Enterprise (including non-profit), Unlimited or Developer edition


We’re going to configure MailChimp to send a message to Salesforce automatically, whenever someone unsubscribes from our MailChimp mailing list. That message will be received by a web page, hosted by salesforce.com, that will query related Salesforce CRM contact or lead records, and mark any as “opted out” of future email communication.

In practical terms, we’ll set up a MailChimp “WebHook” to send the message, and a Salesforce Visualforce page that will receive the message, and then trigger some custom Apex code to query and update any lead or contact records that have the same email address as that of the unsubscribed list member.

If you’d like to explore an already-configured Salesforce environment, including all the elements described in this article, you can login here

Step 1: Install the Salesforce AppExchange Package

The code described in this article can be installed as a package from the Salesforce AppExchange – click to install now (requires login, opens in new window).

The package contains a Visualforce page named “Unsubscribe,” an Apex class named “UnsusbscribeController,” and a static resource named "WebHooksConfig."

If you’re interested in the geeky, technical details: the Apex class acts as the Visualforce page’s custom controller (and includes unit test code). The static resource is an XML file that holds a "secret" code designed to enhance the security of the communication between MailChimp and Salesforce (more about that below). You can view the source code for these items:

Step 2: Create a Force.com Site

As you may know, Force.com Sites are a relatively-new feature, and allow you to set up public-facing, data-driven websites, hosted by salesforce.com. We’re going to set up a Force.com Site whose only purpose is to receive the unsubscribe message posted by MailChimp. Therefore, the page isn’t really "public-facing," at least not for the human public, but is designed only to listen for WebHook messages from MailChimp and act on them accordingly.

You can set up your Force.com Site by going to Setup | Develop | Sites, or by following: this link (requires login, opens in new window).

If you’re creating your first Force.com Site, you’ll be asked to register a Force.com domain name; register any valid domain name that you like, and which is available, then proceed to the next step.

Press the "New" button to create a new Force.com Site and enter the following values – you can leave all the other fields as-is:

  • Site Label: webhooks
  • Site Name: Webhooks
  • Site Description: Handles data posted from MailChimp Webhooks
  • Default Web Address: webhooks
  • Active: Checked

Step 3: Add the Visualforce page "Unsubscribe" to your Force.com Site

Click the "Edit" button in the section titled "Site Visualforce Pages" and add the page titled "Unsubscribe," which you installed with the private AppExchange package. (See notation "A" in the screenshot below for the location of the "Edit" button. If you need to get to this page, click Setup | Develop | Sites and then the label of your Force.com Site.)

Edit Force.com Site details - click Setup | Develop | Sites

Edit Force.com Site details – click Setup | Develop | Sites

Step 4: Configure Site Permissions

Press "Public Access Settings" (see notation "C" in the screen shot above) and scroll down to "Field Level Security." Make sure that both the Contact and Lead objects’ "Email Opt Out" field are marked "Visible." Next scroll down to "Standard Object Permissions" and make sure that "Read" is checked for "Leads."

Note that if you want to view the "Email Opt Out" field in your contact or lead detail page, you may have to add it to the page layout, if it’s not there already.

Step 5: Determine the URL

Note your Site’s "Secure Web Address" (see notation "B" in the screen shot above). If we append "Unsubscribe," we have the URL for our Visualforce page that listens for the messages sent by MailChimp to Salesforce. For example, the URL for my listener page is:


The nature of Webhooks requires that our listener page be on a public-facing website, unprotected by a password or session ID. It is possible, then, that someone who knew the URL and the format of the data, could post fake information, thereby inducing us to update our records. In this case, that would mean tricking us into marking a lead or contact as having opted-out of email communication.

We can enhance security somewhat by requiring that a "secret" code be passed to our listener page along with the WebHook data. If that code were missing or incorrect, Salesforce would simply do nothing, and the caller would be none the wiser.

The AppExchange package that you installed in the first step is pre-configured with a "secret" code of _I_Love_MailChimp_. You can change this code to another value that only you’ll know by editing the static resource file that you installed with the AppExchange package. The static resource is a very brief XML document, including the line below; to use your own code, just modify the "code" attribute:

<webhook id="unsubscribe" code="_I_Love_MailChimp_"/>

We have to pass this "secret" code to the listener page as part of the URL. Therefore, the complete URL for my page that’s listening for MailChimp WebHook messages is:


Yours will be different, of course, at least at the start of the URL.

Step 6: Set up the MailChimp Webhook

The final step is to set up the MailChimp Webhook; that is, we need to tell MailChimp the URL of the listener page that is waiting for messages about unsubscribed list members. If you haven’t already, log in to your MailChimp account, and navigate to the list you want to configure. Select "List Tools" and then "WebHooks."

In the "webhook URL" field enter the URL as described in step 5 above. Under the section labeled "What type of updates should we send?" check "Unsubscribes," and check all the boxes under the section labeled "Only send updates when a change was made by …" Save your changes

Ta Da!

That’s it! Now MailChimp will automatically notify Salesforce whenever someone unsubscribes from your mailing list. Salesforce, in turn, will search for lead or contact records that have a matching email address and mark them as "Opted Out" of future email communication.

Useful Links