May 3, 2010

Automatically Create Salesforce CRM Leads for New Subscribers

MailChimp and Salesforce CRM can communicate with each other and automatically handle those tedious – but so important – data synchronization chores. In this post, we’ll see how easy it is to have Salesforce CRM automatically create a lead record whenever someone subscribes to your MailChimp list.

(You may also find this related post, Synching Unsubscribes with Salesforce, useful.)


The techniques described in this post require the following:

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

How it Works

On the MailChimp side, we’ll set up a WebHook which will send a message to a specified URL whenever someone subscribes to your MailChimp list. That message will contain data about the subscriber, including the subscriber’s email address and values for your list’s merge fields.

On the Salesforce CRM side, we’ll set up a simple Visualforce page which will "listen" for the MailChimp WebHook messages. That page will run custom code that’ll parse the message data and create new lead records accordingly. The code, written in’s Java-like Apex language, will perform the following tasks, in order:

  1. Check the incoming message for a "secret" code
    The presence of this code in the message data means that we can be reasonably sure that the message is coming from our MailChimp WebHook, and not from someone trying to get us to create a new lead record. (We can’t verify the IP address of the MailChimp server which sends the WebHook message because the address is not known in advance and could change at any time.)
  2. Determine the merge-tag-to-lead-field mapping
    The code parses an XML-formatted configuration file that describes the mapping of MailChimp merge tags to Salesforce CRM lead fields.
    If the default mappings aren’t suitable for your setup, you can easily edit the configuration file so that the code will map your particular set of MailChimp merge tags to your organization’s standard or custom lead fields. More on that below.
  3. Create, populate and save a new lead record
    The code will map the merge tag values in the WebHook message to the lead fields, and then save the lead in Salesforce CRM. You can also elect to have Salesforce CRM run your organization’s default lead assignment rule after it creates the new lead.

The Apex code is designed to be "insensitive" to configuration and data errors. For example, if you map a MailChimp merge tag to a Salesforce lead field which doesn’t actually exist, or if the WebHook data can’t be converted to the type expected by the destination lead field, then the code will log the resulting error and continue its work undeterred. You can view the error log in Salesforce by going to Setup | Monitoring | Debug Logs. The errors (i.e. Apex exceptions) are caught before the Visualforce page can display them so that we don’t provide any hints to unauthorized users.

Mapping Merge Tags to Lead Fields

The configuration file provided with the accompanying code (see below) defines default mappings of MailChimp merge tags to Salesforce CRM lead fields. You can easily customize the mappings by editing the configuration file, using any text editor, and entering the names of your list’s merge tags and Salesforce CRM lead fields. You can map to both standard and custom lead fields but, as of this writing, the code supports only custom lead fields that accept text values, including picklists.

Table 1: Default Merge Tag to Lead Field Mappings
From MailChimp Merge Tag To Salesforce CRM Lead Field*
PREFIX Salutation
FNAME FirstName
LNAME LastName
URL Website
MOBILE MobilePhone
EMPLOYEES NumberOfEmployees
LOCATIONS NumberOfLocations
ADDRESS (Address-related lead fields**)

* The mapping uses the Salesforce "API Name" for each lead field. This name may differ from the field’s display label; for example, the first name field is typically labeled "First Name" but has an API name of "FirstName" (no space). Similarly, if you have a custom lead field, labeled "My Custom Field," for example, its API Name will always end with "__c" and might be something like "My_Custom_Field__c." To view the API Name for any lead field, go to Setup | Customize | Leads | Fields; click on the field’s label and note the "Field Name."

** Merge tags of type "address" are treated differently than others; a MailChimp address-type merge tag actually comprises "sub-tags" for the number and street, postal/zip code, state/province, etc. Therefore, the configuration file in the accompanying code lets you specify the name of the MailChimp address-type merge tag that should be examined for the lead’s address. The code will then properly set the values for the lead’s street, city, state and postal code.


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 the following items:

  • Visualforce page: SubscribeLead view source
    Salesforce Visualforce page that "listens" for MailChimp WebHook messages
  • Apex class: SubscribeLeadController view source
    Controller class for SubscribeLead Visualforce page; parses the posted WebHook data and creates a Salesforce CRM lead. Includes required unit test code.
  • Static Resource: SubscribeLeadConfig view source
    XML configuration file. You can modify the values in this file if you want to customize the mappings of MailChimp merge tags to Salesforce CRM lead fields
  • Custom lead field: MailChimp ID
    This field, whose "API name" is MailChimp_ID__c, holds the unique MailChimp ID of the list subscriber, and is configured as an "External ID" field in Salesforce. This will be useful in the future for updating subscriber information

Step 2: Create a Site to “Listen” for messages from MailChimp

If you already created a Site according to this related post, then skip to step 3

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

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

Press the “New” button to create a new 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 by MailChimp WebHooks
  • Default Web Address: webhooks
  • Active: Checked

Step 3: Add the Visualforce page “SubcribeLead” to your Site

Click the “Edit” button in the section titled “Site Visualforce Pages” and add the page titled “SubscribeLead,” which you installed with the 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 Site.)

Edit Site details - click Setup | Develop | Sites

Edit 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 any lead fields which you want to update automatically are marked “Visible.” Next scroll down to “Standard Object Permissions” and make sure that “Read” is checked for “Leads.”

Step 5: Determine the URL for the "listening" Visualforce page

Note your Site’s “Secure Web Address” (see notation “B” in the screen shot above). If we append “SubscribeLead,” we’ll get the URL for the Visualforce page that’ll receive the MailChimp messages. For example, the URL for my Visualforce page is:

The nature of Webhooks requires that our listener page be on a public-facing website, so it is theoretically possible that someone who knew the URL and the format of the data could post fake information and trick us into creating new leads. We can reduce the likelihood of that happening 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 CRM would simply do nothing, and the caller would be none-the-wiser.

The pre-configured “secret” code is _I_Love_MailChimp_. You can change this code to another value that only you’ll know by editing the static resource file “SubscribeLeadConfig,” which you installed with the AppExchange package; simply modify the “code” attribute of the “config” element:

<config id="subscribeLead" 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 below – yours will be different, according to the domain of your site and the code you choose:

Step 6: Set up the MailChimp WebHook

The final step is to set up the MailChimp Webhook. 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 “Subscribes,” and check all the boxes under the section labeled “Only send updates when a change was made by …” Save your changes

Done and done!

Now MailChimp will automatically notify Salesforce CRM when someone subscribes to your MailChimp list, and Salesforce CRM will automatically create a new, corresponding lead record (unless one with the same email address already exists).

Useful Links