MailChimp Form Handler

This script is an interface between the form on your page and the MailChimp API.

Data from your form is submitted to this script, which is then processed and sent on to MailChimp.

We've taken the hard work out of setting up the API integration. By configuring the settings in the forms/mailchimp.php file you can easily add subscribers to your lists in MailChimp through the forms on your website.

Subscribers will be added to your MailChimp account, on a list you specify. MailChimp handles double opt-in and provides feedback when the user has already subscribed.

You may then do what you wish with the list of subscribers such as send email through MailChimp, or export them to use on another service.

To use the mailchimp.php form handler you will need the following

• A free MailChimp account
• A MailChimp API Key (Get this from your dashboard)
• A MailChimp List ID (Get this from your dashboard)
• A PHP server > 5.3
• Configuration of settings in forms/mailchimp.php

API keys are easy to create. It only takes a couple minutes and only needs to be done once.

• Log in to your MailChimp account
• Click your name in the top-right corner of the screen. A menu will pop out.
• Navigate to [Account] > [Extras] > [API Keys]
• Click Create a Key
• A new row should appear on your list of keys
• A long random string of text is listed under API Key. That is your API key.

Lists in MailChimp store collections of subscribers. It is necessary to set up a list to store the subscribers you collect from your forms. You will need the ID of the list you want to use.

If you have not yet set up a list, follow the instructions below. If you already have a list set up, skip these and move to step 2.

1. Set up a list (Audience)

   • Log in to your MailChimp account
   • Click Audience on the main menu at the top of the page
   • Click Switch Audience and choose View Audiences from the dropdown list
   • Click the Create Audience button
   • Ignore a message about Tags , Click Create Audience
   • Fill in the details to your liking
   • Tick the "Enable double opt-in" box
   • Click Save

2. Get the list ID (Audience ID)

   • Click Audience on the main menu at the top of the page
   • Click Switch Audience and choose View Audiences from the dropdown list
   • Click the list you would like to use to collect your subscribers
   • On the submenu, click Settings
   • Choose Audience Name and Defaults from the dropdown
   • In the right hand column you will see Audience ID
   • Note that list ID for use in your configuration file.

Every setting you need to set up your MailChimp integration is in forms/mailchimp.php.

Configuration takes the form of PHP variable declaration. All of the variables are already set up with dummy data.

Change the values on the right hand side of the = sign leaving the quotes intact.

Variable	Description
$apiKey	Copy your API key here from the MailChimp dashboard.
$listId	Use the Audience ID you gathered using the instructions above.
$emailField	Enter the name of your form's email field (usually email).
$mergeFields	Please see section on $mergeFields configuration below.
$status	Specify the user's status when they have submitted the form. Use subscribed for single opt-in. pending will cause the user to receive an opt-in confirmation email from MailChimp.
$successMessage	This message will be passed back in the server's JSON response to the browser, and will be shown in the data-success-message element.
$alreadySubscribed	A message to be shown to the user when the provided email is already on the list.
$checkConfirmation	A message to be shown to the user when they have alredy subscribed (status: pending) but did not yet click the confirmation link in their email inbox.
$recaptchaSecretKey	Optional. If using reCAPTCHA, place your secret key found on your reCAPTCHA admin page. See our reCAPTCHA documentation for more.
$recaptchaErrorMessage	Optional. If using reCAPTCHA, this is an explanation to the user for when a reCAPTCHA error occurs.

In configuring forms/mailchimp.php you must fill out the $mergeFields array to match the fields in your MailChimp list with the fields you pass in from your form inputs.

This is a more advanced topic, hence why detail is given here.

$mergeFields is an array containing names of all other form inputs you want to send to MailChimp besides the email field.

The array is used to match your MailChimp list fields with the data provided in your form fields.

The basic steps required to fill the array are as follows:

• Copy the existing line and create a new line for each input. This helps keep the code formatting intact.
• Only change the text within the " double quotes.
• On the left side of => Type the MailChimp field name (usually in CAPS).
• On the right side of => type the matching input name from your form.

Example

If your subscribe form takes more fields such as First Name, Last Name and Phone you would add a line for each.

On the left of the arrow is the MailChimp field name. On the right of the arrow is the form input name.

$mergeFields = array( 
  "F_NAME" => $_POST["first-name"],
  "L_NAME" => $_POST["last-name"],
  "PHONE" => $_POST["phone"],
);

If the fields provided in your $mergeFields array do not perfectly match the MailChimp list fields, you will receive errors.

To make debugging a little easier, the script will pass back the detailed MailChimp API error object via JSON to the browser, which is then displayed in the console. You can open the console to get a detailed report on the MailChimp error as you are testing your form configuration.

Common Errors

Error	Description
mailchimp.php (0 error)	Check your web browser console for a javascript error. Ths usually means that the request could not be sent from the browser.
Internal Server Error	This is a very general error and can be hard to diagnose. Generally this is a syntax error in your mailchimp.php file. You can copy your code to an online PHP code checker to help identify problems in the syntax, or uncomment the first two lines of forms/vendor/mediumrare/mailchimp_subscribe.php to reveal more descriptive PHP error messages. To read the message, open the network tab of your web browser developer tools and inspect the mailchimp.php request. The detailed error message will be readable in the response tab.
200 JSON Parse error, unexpected '<'	The server is not returning JSON, instead it is producing error text in HTML format, so jQuery can't handle it as JSON. Check the network tab in your browser developer tools, locate the mailchimp.php request and view the response to read the full error text.
There was an error verifying the Google reCaptcha	Check that your secret key is properly set in smtp.php.