MailChimp Lists plugin for Craft CMS 3.x

Create, manage and monitor your MailChimp Lists from within Craft., _(*2)

Screenshot , _(*3)

Requirements

This plugin requires Craft CMS 3.0.0-RC11 or later., _(*4)

Installation

To install the plugin, follow these instructions., _(*5)

Open your terminal and go to your Craft project:, _(*6)
```
cd /path/to/project
```

Then tell Composer to load the plugin:, _(*7)

composer require lukeyouell/craft-mailchimplists

In the Control Panel, go to Settings → Plugins and click the “Install” button for MailChimp Lists., _(*8)

Configuring MailChimp Lists

You will be required to supply a MailChimp API key which is used to source the relevant data center and authenticate requests., _(*9)

Your API key is available here., _(*10)

A MailChimp account is required, if you don't already have one click here to create one., _(*11)

Free & paid plans are available., _(*12)

Using MailChimp Lists

Once you have provided the plugin with your MailChimp API key you will be able to create, manage and monitor your lists directly from within Craft., _(*13)

Example Form

Your list subscription form template should look something like this:, _(*14)

Form Parameters

Name	Required	Hashed	Expected value
`listId`	Yes	Yes	The unique id for the list
`status`	Yes	Yes	`subscribed`, `unsubscribed`, `cleaned` or `pending`
`email_address`	Yes	No	Email address for a subscriber
`email_type`	No	No	`html` or `text`
`merge_fields[]`	No	No	An individual merge var and value for a member
`interests[]`	No	No	The name of this field is the ID of the interest in question.
`language`	No	No	If set/detected, the subscriber’s language ISO 3166 Country Code
`vip`	No	No	VIP status for subscriber
`location[latitude]`	No	No	Subscriber location latitude
`location[longitude]`	No	No	Subscriber location longitude

The above field names are case-sensitive., _(*15)

Redirecting After Submit

If you have a redirect hidden input, the user will be redirected to it upon successful submission. This must also be a hashed value., _(*16)

If you don't have a redirect hidden input, the plugin will respond with json (handy for debugging), _(*17)

Ajax Submissions

You can optionally post submissions over Ajax if you’d like. Just send a POST request to your site with all of the same data that would normally be sent (except for the redirect field), _(*18)

$('form').submit(function(ev) {
  // Prevent the form from actually submitting
  ev.preventDefault();

  // Send it to the server
  $.post({
    url: '/',
    dataType: 'json',
    data: $(this).serialize(),
    success: function(response) {
      if (response.success && response.statusCode == 200) {
        alert('Success!');
      } else if (response.statusCode !== 200) {
        alert('MailChimp error: ' + response.body.title)
      } else {
        alert('An error occurred. Please try again.');
      }
    }
  });
});

Example Responses

Successful

{
   "success": true,
   "statusCode": 200,
   "reason": "OK",
   "body": {
      "id": "24d2b4y97c4fe95a2d6a3d3ba2018cb0",
      "email_address": "joe.bloggs@email.com",
      "unique_email_id": "84a5q243cd",
      "email_type": "html",
      "status": "subscribed",
      "merge_fields": {
         "FNAME": "Joe",
         "LNAME": "Bloggs",
      },
      "stats": {
         "avg_open_rate": 0,
         "avg_click_rate": 0
      },
      "ip_signup": "",
      "timestamp_signup": "",
      "ip_opt": "8.8.8.8",
      "timestamp_opt": "2018-02-21T13:37:36+00:00",
      "member_rating": 2,
      "last_changed": "2018-02-21T13:37:36+00:00",
      "language": "",
      "vip": false,
      "email_client": "",
      "location": {
         "latitude": 0,
         "longitude": 0,
         "gmtoff": 0,
         "dstoff": 0,
         "country_code": "",
         "timezone": ""
      },
      "list_id": "t74m4dbg9r"
   }
}

MailChimp Error

{
   "success": true,
   "statusCode": 400,
   "reason": "Bad Request",
   "body": {
      "type": "http://developer.mailchimp.com/documentation/mailchimp/guides/error-glossary/",
      "title": "Member Exists",
      "status": 400,
      "detail": "joe.bloggs@email.com is already a list member. Use PUT to insert or update list members.",
      "instance": "a6d8eac9-3456-123a-a01b-22r4342d6432"
   }
}

Request Failed

{
   "success": false,
   "reason": "cURL error 6: Could not resolve host: us17.api.mailchimp.co.uk (see http://curl.haxx.se/libcurl/c/libcurl-errors.html)"
}

Overriding Plugin Settings

If you create a config file in your config folder called mailchimp-lists.php, you can override the plugin’s settings in the Control Panel. Since that config file is fully multi-environment aware, this is a handy way to have different settings across multiple environments., _(*19)

Here’s what that config file might look like along with a list of all of the possible values you can override., _(*20)