MailChimp Integration

Connect your Alchemer and MailChimp accounts to automate contact creation and management. You'll also have the ability to use your MailChimp subscriber details to populate data into your Alchemer surveys (a great way to keep your contact records up to date).

The Alchemer MailChimp Action allows you to:

1. Create or update contacts in MailChimp from Alchemer survey submissions using the MailChimp Push Action. There are three push methods:

• Upsert -  An upsert is a conditional action: update if a record exists, insert if it doesn't. The contact email address will be used to look for a matching record in MailChimp. If an email address already exists in a list, the existing contact record will be updated. If there is no match for an email address in MailChimp, a new contact record will be created. 
• Insert - Insert is the term used for creating a new contact. 
• Update - An update is an update of an existing contact. 

2. Pull contact information (MailChimp subscriber details) into questions/fields within your Alchemer survey using a MailChimp Pull Action.

Integration Setup

Before you get started, note that you will need your MailChimp API Key to set up the integration within Alchemer. Visit the MailChimp API Key documentation for instructions on obtaining your key. 

1. To get started connecting your MailChimp account in Alchemer, go to Integrations > Data Connectors on the left hand navigation menu and locate the MailChimp integration. Click the Configure button to get started.
2. On the Authentication tab, provide an Account Label (this is just a name for the account that is internal to you and your fellow Alchemer users) and the MailChimp API Key (both fields are required). If you don't have your API Key readily available, visit the MailChimp API Key documentation for instructions.
   
3. Once you are finished setting up your integration click Save. You will see a status of Enabled. Once your integration is enabled you can add the MailChimp Action to your surveys to push/pull contact data.
   

MailChimp Push Action: Push Info From a Alchemer Survey to MailChimp List Fields

The push method for Alchemer's MailChimp Action allows you to automate the contact creation and management process. Use your Alchemer survey to collect contact details and then sync them to your MailChimp contact list. You can use the push method to update, insert, or upsert. 

The push action requires collecting and sending an email address to MailChimp to either create new contacts or update existing ones. If your push action will result in the creation of a new contact (both inserts and upserts will create new contacts), you'll also need to push a Status for this new subscriber. Status has possible values of subscribed, unsubscribed, pending, and cleaned. 

MailChimp Action Push Setup

Your push action must be on a page that follows any survey questions that will be sent to MailChimp. We recommend placing the push action on your survey's Thank You page.

1. Create a survey and add any questions/fields that are necessary for you to push to a contact within MailChimp. At a minimum, add an Email Question to your survey (an email address is required to both create and update a contact in MailChimp).
2. Click the Action link on the page where you wish to place your action and locate the MailChimp action within the Integrations section. Click the +Add button.
3. Provide an Integration Title for your action (This is a title that is internal to you and your fellow Alchemer users; it should represent the purpose of the action.) 
4. Under Select a MailChimp Integration your integrations will be identified by the account label that you provided when connecting your MailChimp and Alchemer accounts on the Integrations page. Select one.
5. Using the Select an Object dropdown menu, choose the MailChimp list you wish to push to. Currently, the lists object is the only available object type.
6. Select Push Data to MailChimp under the Method section. Select the push method that you wish to use:
   • Upsert - If the provided email address exists in MailChimp, the survey response will be used to update an existing contact record with that email. If an email address doesn't exist, a new contact record will be created with the provided email address. An email address is required to upsert in MailChimp. Status is also a required field in MailChimp.  
   • Insert - Insert is the term used for creating a new contact record. An email address and status are required to insert a new contact in MailChimp.
   • Update - An update is an update of an existing contact record. An email address (unique identifier) is required to reference the contact record that should be updated. 
7. The next step requires identifying the question/field in the survey that contains the respondent's email address as this is required for all push methods. The email address must be passed into or collected on the survey and stored in either a question or Hidden Value Action. Use the dropdown under Question containing the MailChimp Contact Email to select the survey question/field that contains the respondent's email.
   
   
   1. In the event that you need to pass in the email address as a URL variable or reference it via a merge code, select the Static Value (Merge Codes, etc.) option. You will see an additional field and can input a static value or use the merge code helper to reference the email address:
      
   2. Also, if you are inserting a new contact, make sure to map this email question/field to the email field in MailChimp (see step 8 below).
8. Next, map your Alchemer fields to your MailChimp Fields under the Map Fields section. 
   1. If you selected either the Insert or Upsert method the MailChimp Required fields (Email Address and Status) are added by default. 
      1. For Email Address simply select the Alchemer field where the email address is collected/stored to finish the mapping. 
      2. The Status is ready to go but you can change the default value to something other than subscribed (i.e. unsubscribed, pending, or cleaned.)
   2. Map the rest of the fields that you wish to send as part of your push. 
      1. In the left column, select the Alchemer question/field from which you want to send data.
      2. In the right column, select the corresponding MailChimp List Field, that you want to send the question data to.
      3. Use the Default Value field to pass information to MailChimp in the event that the Alchemer filed is blank. Merge codes are also supported in this field when paired with the Static Value option in the first dropdown menu.
      4. Use the Add another mapping link to add more field pairs as needed.
   3. See the Mapping Fields Section of this tutorial for additional details about sending data to MailChimp.
9. Once you have finished mapping your fields, go to to the Logic tab if you only wish to trigger your MailChimp push under certain conditions. Make sure to Save Action when finished.

MailChimp Pull Action: Pull Info From MailChimp List Fields into a Alchemer Survey

The pull method for Alchemer's MailChimp Action allows you to use your MailChimp contacts' subscriber details within your Alchemer surveys.

MailChimp Action Pull Setup: Pull Info MailChimp List Fields into a Alchemer Survey 

When pulling contact data from MailChimp into Alchemer, the survey will need to be able to identify the contact whose information should be pulled in. This is done by providing the contact's email address. 

Pull Action Placement Requirements:

• The pull action must be on a page that follows the field in the survey that contains the email address. 
• The pull action must also precede any fields that it will be populating. Pull actions can be on the same page as the fields they populate however they must come before those fields on the page. 

1. On a page that meets the above placement requirements, click the Action link and locate the MailChimp action within the Integrations section. Click the +Add button.
2. Provide an Integration Title for your action (This is a title that is internal to you and your fellow Alchemer users; it should represent the purpose of the action.) 
3. Under Select a MailChimp Integration your integrations will be identified by the account label that you provided on the Integrations page when connecting your accounts. Select one.
4. Using the Select an Object dropdown menu, choose the MailChimp list you wish to pull from. Currently, the lists object is the only available object type.
5. Select Pull Data from MailChimp under the Method section.
6. An email address is required to reference an existing contact record in MailChimp.
   
   
   1. This email address must be passed into or collected on the survey and stored in either a question or Hidden Value Action.
   2. Use the dropdown under Question containing the MailChimp Contact Email to select the survey question/field that captures the respondent's email. This field must be on a page that precedes the pull action you are setting up.
      
   3. In the event that you need to pass in the email address as a URL variable or reference it via a merge code, select the Static Value (Merge Codes, etc.) option. You will see an additional field and can input a static value or use the merge code helper to reference the email address:
      
7. Next, map your MailChimp fields to your Alchemer fields under the Map Fields section. 
   1. In the left column, select the Alchemer question/field that you want to populate. 
   2. In the right column, select the corresponding MailChimp List Field from which you want to pull data.
   3. Use the Default Value field to pass a default value into Alchemer in the event that the field is blank for that record in MailChimp. Merge codes are also supported in this field when paired with the Static Value option in the first dropdown menu.
   4. Use the Add another mapping link to add more field pairs as needed.
      
8. Once you have finished mapping your fields, you can optionally apply conditions for triggering your MailChimp push on the Logic tab. Make sure to Save Action when finished.

Map Fields

When mapping Alchemer Questions to MailChimp list fields there are a couple of requirements to ensure your integration works properly. 

Push Action: Required MailChimp List Fields

There are two default required fields in MailChimp. In addition, list fields may be set up as required in MailChimp by the list creator. 

The default required fields in MailChimp are Email Address and Status. Status has possible values of subscribed, unsubscribed, pending, and cleaned. Whenever your MailChimp action may result in the creation of a new record (insert and upsert) we will add these fields by default. 

• For Email Address, simply select the Alchemer field where the email address is collected/stored to finish the mapping. 
• The Status is ready to go but you can change the default value to something other than subscribed (i.e. unsubscribed, pending, or cleaned).

Push and Pull: Matching MailChimp List Field Type

For both the push and the pull it is important to ensure that your Alchemer Reporting Values and question validation settings are compatible with the List Field Type in MailChimp. 

For example, MailChimp's default Birthday list field includes a month and day only (in either MM/DD or DD/MM) format. As such, you cannot map the Birthday field to Alchemer's Date question. Instead, you should pull this information into a Textbox question. If you require validation on this field you'll need to use RegEx to validate for month and day (or day and month). 

Push To and Pull From MailChimp Groups (aka Interests)

If you are using MailChimp Groups (aka Interests) you can push and pull from these as well! You can push data from or pull data into either a Hidden or Checkbox Group. You can push data from (or pull data into) either a Alchemer Radio Button or Checkbox question to interests.

The following mappings are supported:

• Push from Alchemer Checkbox Question to MailChimp Checkbox Group or Hidden Group
• Push from multiple Alchemer Radio Button Questions (One per group name) to MailChimp Checkbox Group or Hidden Group
• Pull from MailChimp Checkbox Group or Hidden Group into a Alchemer Checkbox Question
• Pull from a MailChimp Checkbox Group or Hidden Group into a multiple Alchemer Radio Button Questions (One per group name)

Push from Alchemer Checkbox Question to MailChimp Checkbox Group or Hidden Group

Let's take the following example groups in MailChimp: Donating, Volunteering, Events. Note, this is a Checkbox Group in MailChimp, meaning one email can have multiple groups. This would work for Hidden Groups in MailChimp as well, as it allows for multiple selections.

We can push data from a similarly formatted Alchemer Checkbox Question. 

The mapping for a Alchemer Checkbox Question to MailChimp Checkbox/Hidden Group would look like so:

Push from multiple Alchemer Radio Button Questions (One per group name) to MailChimp Checkbox Group or Hidden Group

Let's take the following example groups in MailChimp: Donating, Volunteering, Events. Note, this is a Checkbox Group in MailChimp, meaning one email can have multiple groups. This would work for Hidden Groups in MailChimp as well, as it allows for multiple selections.

We can push three Alchemer Radio Button Questions, one per group, like the below example. You cannot push multiple Radio Button questions to one group in MailChimp.

The mapping for separate Alchemer Radio Button Questions to MailChimp Checkbox/Hidden Group would look like so:

Requirements for Pushing to Radio Button questions

• You must have a separate Radio Button question per each group in MailChimp 
• The reporting values for each separate Radio Button question must be in one of the following formats:
  • 0,1
  • True, False (case insensitive)
  • Yes, No (case insensitive)

Pull from MailChimp Checkbox Group or Hidden Group into a Alchemer Checkbox Question

You can pull data from checkbox or hidden interests to populate a Radio Button or Checkbox question. 

Let's take the following example groups in MailChimp: Donating, Volunteering, Events.

These can populate a similarly formatted Checkbox question.

The mapping for a MailChimp checkbox/hidden group to a Alchemer checkbox question would look like so:

Pull from a MailChimp Checkbox Group or Hidden Group into a multiple Alchemer Radio Button Questions (One per group name)

You can pull data from checkbox or hidden interests to populate a Radio Button or Checkbox question. 

Let's take the following example groups in MailChimp: Donating, Volunteering, Events.

In order to populate three groups into Radio Buttons questions, we must populate into three separate Radio Button Questions, one per group, via a pull (see below example).

The mapping for a MailChimp Checkbox/Hidden Group to separate Alchemer Radio Button Questions would look like so:

Requirements for Pushing to Radio Button questions

• You must have a separate Radio Button question for each group in MailChimp 
• Your reporting values for each separate Radio Button question must be in one of the following formats:
  • 0,1
  • True, False (case insensitive)
  • Yes, No (case insensitive)

FAQ & Troubleshooting

What version of the MailChimp API is used in this integration?

We use version 3.0 of the MailChimp API.

I'm using the Insert or Upsert Push Method and a contact was not created.

At the very least, Email Address and Status (with a value of either subscribed, unsubscribed, pending, cleaned) are required to create a new contact record in MailChimp.

Make sure that an email address was provided in your survey and that the email address was mapped to the Email Address List Field in MailChimp. Make sure that you have also passed over a Status. Learn more in the Mapping Fields Section of this tutorial. 

Does your pull include a birthday?

MailChimp's default Birthday list field includes a month and day only (in either MM/DD or DD/MM) format. As such, you cannot pull this fields into Alchemer's Date question. Instead, you should pull this information into a Textbox question. If you require validation on this field you'll need to use RegEx to validate for month and day (or day and month).

One or more of my fields was not passed to MailChimp.

Alchemer validates the data that you are trying to push to MailChimp to make sure that it is pushed in the format expected by MailChimp.

If you try to push a value that is not expected by MailChimp, that value will not be pushed successfully. This will not affect the entire push action, only the specific value.

For example, let's say that you are passing a URL/website to MailChimp from Alchemer. In this case, MailChimp expects the data in the format of text.text (note the 'dot'). As such, trying to pass "alchemer" would fail, whereas "alchemer.com" would succeed.

My MailChimp Action did not pull/push data.

If your MailChimp Action is failing to push or pull data, check the Action Log for an associated survey response.

1. Go to Results > Individual Responses, and click on one of the responses associated with a failed action.
   
2. On the Action Log tab and locate your MailChimp Action (identified by Integration title you provided within the action). Here, you can view the action input/output and refer to any errors that might be presented. If you are using a push and no data is being passed into MailChimp, this is likely due to an unexpected value being pushed into a specific field (e.g. text being pushed to a number field).