# MailChimp Form Handler

A server-side PHP script to handle adding subscribers to a MailChimp list. Works in tandem with frontend script to provide a seamless experience.

###

What is it?

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.

###

Requirements

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`

###

Obtain Your MailChimp API Key

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.

###

Get a List ID

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.

MailChimp recently started referring to lists as audiences. Please consider the word list and audience interchangable.

###

Configure `mailchimp.php`

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.

###

`$mergeFields` configuration

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"],
    );

It is not necessary to include the `email` field as this is collected in the `$emailField` variable (see table above).

###

Troubleshooting

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`.