Integral MailChimp User Guide

Setup Wizard

Integral License Key

Insert License Key
  1. Click the “set your Integral Plugin License key” in the setup wizard or navigate to the Integral MailChimp Options page.
  2. Find the License Key that was provided in your Purchase Receipt email.
  3. Insert the License Key into the field and submit.

MailChimp API Key

Insert API Key
  1. Click the “set your MailChimp API key” in the setup wizard or navigate to the Integral MailChimp Options page.
  2. You can find this key by logging into your MailChimp account and then going here.  (What is a MailChimp API Key?)
  3. Insert the API Key into the field and submit.

Default MailChimp List

Select Default List
  1. Click the “select a default MailChimp Email List” in the setup wizard or navigate to the Integral MailChimp Options page.
  2. Select one of the available MailChimp lists.
  3. If you have not created at least one list in your account, you will need to do that before using the plugin.

Sync Merge Tags and Users

Syncing Merge Tags
  1. Click the “sync your Merge Tags and Users” in the setup wizard or navigate to the Integral MailChimp List Management page.
  2. Select one of the available MailChimp lists. NOTE: At the very least, you’ll want to manage the Merge Tags for the default list you chose in the previous step.
  3. Drag and drop any Merge Tags from the Inactive group into the Active group.
  4. If you accidentally dragged one you didn’t intend to, simply drag it back.
  5. For a little more info on the groups (Active, Inactive, and Unused) go here.

Register Webhooks

Register Webhooks
  1. Click the “register the MailChimp webhooks” in the setup wizard. (What are webooks?)
  2. NOTE: This is a “behind-the-scenes” kind of operation and for the most part you’ll never see the webhooks do anything. Your WordPress user accounts will simply have their info updated if that user makes changes in their MailChimp account.

Email Campaigns

Creating an Email Campaign

Create Campaign Email
  1. Add a Title for the Campaign. This will only be used for administrative purposes when viewing the Campaign list and will not be shown to your subscribers.
  2. Add the Subject Line for the Campaign. This is what your subscribers will see.
  3. Select which MailChimp List you would like to send to.
  4. Select an available segment if necessary.
  5. Ensure that the From Name and Email are correct.
  6. The To Name should be left as is for most cases.
  7. Select an available template.
  8. After it loads, hover over and click the region(s) that you would like to change and then edit as you would a WordPress post.
    NOTE: You are only allowed to edit the areas of the template that have been modified for such editing by the template creator.
  9. Once you are satisfied with the changes, you may choose to “Save Draft”, insert an email and “Send Test”, or “Send Email Now!”.
  10. Once your campaign begins to collect statistics, you will see them populated in the Emails List.

Using Custom Templates

The Integral MailChimp plugin supports both MailChimp’s templates and custom ones you create yourself. In order for your custom templates to be editable they must use MailChimp’s template language. The official MailChimp instructions can be found here. Following are the steps necessary to create and add a custom template to MailChimp and have it be accessible when creating a new campaign.

Quick Start

Want to get going quickly? There are only two types of tags you need to add to your custom templates to make them editable.

Content Areas

Any area of your template where you want to be able to add / edit text and images needs to have the tag mc:edit=’XXX’ added to it. The XXX must be replaced with a unique name for that content area. For example:

 <div mc:edit='main-content'>Main content placeholder text goes here</div> 

You can have as many editable content areas as you like, just be sure to give each one a unique name. To add an editable content area in the footer of your email, for example, you could put:

 <div mc:edit="footer">Footer content placeholder text goes here</div> 


To make an image in your email template editable you need two tags: mc:edit=’XXX’ and mc:label=’image’. The second tag, mc:label=’image’, tells the plugin to use the built in WordPress media gallery when editing the image. Clicking on an image with this tag will open the media gallery and allow you to choose from your existing pictures upload new ones, just like when you’re editing a post or page.

 <img src="XXX" mc:edit="logo" mc:label="image" alt="" width="800px" height="200px" /> 

As with the content areas, you can have as many editable images as you like. Note: The image width and height tags are read by the plugin and displayed when you hover over the images as you edit the template. That makes it easy to be sure that any new images you are inserting are the correct size.

Power User Tip

If you have a handful of image sizes you use frequently in your custom templates we recommend using a plugin like Simple Image Sizes to add custom image sizes that are automatically created when you upload new pictures to your site. For example, if you have a header image in your emails that is 800 pixels wide by 200 pixels tall, you would use Simple Image Sizes to add a new image size with those dimensions and title it Email Header or something similar. From now on any images you upload (that have the correct proportions) will get a version with those dimensions created that you can choose when creating new emails.

Starting from Scratch

If you’re starting from scratch, the easiest way to begin is by using one of the existing MailChimp templates as your starting point.

1. Log into your MailChimp account, choose templates from the menu at the top of the screen, then click on the Create Template button on the top right of the templates screen.

2. Select Themes — you can use any template but we recommend starting with one of the classic themes as these require the least modifications. You can tell which are classic as it is listed under the template name:


3. Selecting the template will open it in a design editor. Make any changes you want and then hit Save and Exit. Give your new template a name when prompted and then hit Save.


4. Your new template will now be listed on the templates page and it will show up as a saved template in the Integral Mail Chimp New Campaign. It will be fully editable.

Using Drag and Drop Templates or Your Own

If you prefer to use one of the drag and drop MailChimp templates, such as any of the basic layout templates, you’ll need to do a bit more work to make it editable. Follow the steps above first, then do the following:

1. Next to your new template click on the drop down menu next to Edit and choose Export as HTML. You will see a warning that if you import this template back into MailChimp later you won’t be able to add, edit or remove any of the drag and drop blocks — you can ignore this warning.


6. Exporting the template will prompt you to pick a name and location on your computer to save it to. Tip: By default it will save the file with the extension .html. Double clicking a file with that extension will open it in your default browser, not an editor. To make it easier save the file with the extension .txt, then open that saved file in your editor of choice.

7. At the top of your new file you will see a lot of inline style tags. Because support for HTML tags and styles varies across browsers and email clients, MailChimp works hard to make sure your email looks the same for everyone regardless of what they’re using to view it. These inline style tags are a key part of how that works and should be left alone unless you have a good understanding of how they work and what you’re changing. You want to scroll down to the start of the actual HTML code, which will look something like this:


8. Now you’re going to find the areas you want to make editable and add the appropriate MailChimp template tag(s). For content areas, which can contain both text and images and which will open up the standard WordPress text editor (like you use to edit posts and pages), add the tag mcedit=’area_name’. The value of the mcedit tag should be a unique name for that content area. In the example below, we’re making the email preview area editable so we use mcedit=’preview_content’.


9. Repeat this process for any other content areas you want to make editable.

10. When you are using a drag and drop template as your starting point the image areas will show up as a table with the class mcpreview-image-uploader — in MailChimp those tables are placeholders for an image editor. In your template you’ll need to replace those with an actual image tag. For example, if you’re starting with the Basic 1 Column Drag and Drop template you’ll see the following where the header image goes:


Replace that table code with an image element that has the appropriate MailChimp template tags, like so:


11. When you are done making your replacements, you’ll simply upload your modified file as a new template in MailChimp. Go back to the very first step, Create Template. This time choose Code Your Own and then select Import HTML. You will be prompted to give your new template a name and select the file to upload.

12. Once uploaded it will open in the visual editor and you will be able to confirm that your editable areas are working as expected. If you missed any you can also edit your code directly on screen and test each change until you have it right. Then hit Save and Exit and your new template is now available. Note: You’ll probably want to delete the first version of it, the one you exported as HTML, just to keep things clean.

Merge Tags

Merge Tag Activation

Drag-n-drop Merge Tags
  1. To activate a Merge Tag for syncing with MailChimp, drag-n-drop it from Inactive to Active and visa versa.
  2. For information on how to take advantage of our hooks for creating your own Merge Tags, click here.

Merge Tag Status

Active Merge Tags


  1. Active Merge Tags are synched to MailChimp whenever a user is added or updated in the system.
  2. They may also be updated when the Webhooks are triggered.
  3. The blue bar on each item indicates that there is a matching Merge Tag in MailChimp, i.e. the activation was successful.
Inactive Merge Tags


  1. Inactive Merge Tags will NOT be synched to MailChimp when a user is added or updated.
  2. The blue bar on each item indicates that there is a matching Merge Tag in MailChimp, which for inactive Merge Tags is irrelevant.
Unused Merge Tags


  1. Unused Merge Tags are tags that exist ONLY in MailChimp and do not have a corresponding tag in your WordPress site.
  2. These will always have a blue bar, which for unused Merge Tags is irrelevant.
  3. To add these tags to your WordPress installation refer to our Developer Guide.

Subscribe Widget

Configure Subscribe Widget

Configure Subscribe Widget
  1. Drag the widget template from the left side into the widget area of your choice to create a new instance of the widget.
    NOTE: You can have as many different instances of the Subscribe Widget as you choose.
  2. Add a Title & Description for the widget.
  3. Choose to allow users to be created in WordPress if they subscribe.
  4. Select which list subscribers will be added to.
  5. Select an available grouping for the subscribers to choose from.
  6. Select which active Merge Tags to allow the user to populate in the form.
    NOTE: You will only see Merge Tags that you have activated for the list you selected above.
  7. Save the widget.

Subscribe Form Code

We are working on adding a shortcode to display subscribe forms on your website as an alternative to the sign up widget. In the meantime, you can use the following method to manually accomplish this.

If you want to display a sign up form outside of a widget area you can use WordPress’s the_widget() function (documentation here) to display a signup form using PHP. You can place the code directly in a template, use a theme (such as Enfold) that supports PHP code blocks in a page or post, or use a plugin like PHP Code for Posts that allows you to insert the code below via shortcode.

In the code example below replace mailchimp-list-id with the actual list id and mailchimp-interest-group-id with the interest group id (instructions for finding those are below).

$instance = array(
'imc-widget-title' => 'Subscribe', //-- optional, only if you want a title to display
'imc-widget-description' => '', //- optional, only if you want a description
'imc-widget-create-user' => true, //- set to true or false depending on if you want a WP user to be created
'imc-widget-display-in-modal' => false, //- set to false. If set to true the form will be hidden and will need a link on your page to trigger opening the form in a modal
'imc-widget-select-list' => 'mailchimp-list-id', //- the MailChimp list id -- easy way to find it is to view source of the list dropdown in the widget
'imc-widget-select-grouping-mailchimp-list-id' => 'mailchimp-interest-group-id', //- optional, if you want to show Interest Groups. View same way as above
'imc-widget-select-mergetags-mailchimp-list-id' => array('FNAME', 'LNAME') //- optional, any merge fields you want displayed.

the_widget(‘IMC\Controllers\Subscribe_Widget_Controller’, $instance); //- use this code exactly as it appears

MailChimp uses custom IDs for the mailing lists and interest groups when accessed via the API. You can not find them in MailChimp itself, only by viewing the source code in the subscribe form widget. What you need to do is add an instance of the widget to any widget area on your site (you don’t need to actually save it, just put it there so you can grab the IDs needed), then right click on the Lists drop down menu and choose view source in your browser. In the screen shot below we’ve highlighted what you need to copy and paste into your code.


Pop Up Subscribe Form

If you would like your email subscription form to open in a modal window (a hidden form that pops up in an over lay window with a semi-transparent background covering the page below) there are two things you need to do.

  1. Check the Display in a Modal Window checkbox in the widget settings for your subscription form.
  2. Add a button or other link to trigger the modal — the thing your site visitors will click to make the subscription form window pop open. Note that the data-target attribute (highlighted below) is set to the id of the subscribe widget (listed at the top of the widget). That is what ties this button to that particular form. You can use multiple forms on the same page, each triggered by a different link or button, by using their ids. When you first create a widget the id won’t be displayed, you need to save it first.

You can see an example of the modal window option in use here: 

Additional Options

Setup Options

Setup Options


  1. In order for the plugin to run efficiently and not overburden the web server with excessive calls to the MailChimp API, we cache as much of the MailChimp data as possible.
  2. Things like MailChimp Lists, Campaigns & Templates all get cached for about an hour at a time.
  3. On occasion it may become necessary to refresh the cache immediately, which is what this button is for.


  1. If you chose to skip the webhook registration during the Setup Wizard, you may initiate that process manually using this button.
  2. For more information on webhooks read this page.

Debug Log

Enabling Debug Logging

Enable Debug Log
  1. If you begin experiencing issues with the plugin not working correctly, the first step should be to enable the Debug Logging.
  2. Once it’s enabled, a new Debug Log menu item becomes available. (See the next guide for details)

Submit Debug Log to Integral

Submit Debug Log
  1. Let’s say you’re creating a new campaign and run into an issue.
  2. Open up a new tab and navigate to the Debug Log page.
  3. Provide a description of:
    1. What you were doing just BEFORE the issue happened and
    2. What happened WHEN the issue occurred (Copy/paste the error message here if possible)
  4. Ensure that your name and email are correct and click submit.
  5. We’ll reply back by email once we’ve reviewed it and notify you of the next steps.