MailChimp Setup

Overview

This document provides instructions on how to add integrate MailChimp with Ultimate Member using the MailChimp extension.

Contents

• Getting started
• Get the MailChimp API Key
• Create an audience
• Configure settings
  • Extension settings
  • User Role settings
• Create a connection
  • Create a connection with the audience
  • General connection settings
  • Configure fields
    
    • Audience fields
    • Merge User Meta widget
    • Field type restrictions
• Add MailChimp field to the registration form
• Account features
• Manual syncing

Getting started #

Main steps to configure the extension:

1. Go to MailChimp and create an account.
2. Create a MailChimp audience.
3. Copy MailChimp API key.
4. Go to your site and install the MailChimp extension.
5. Go to the page wp-admin > Ultimate Member > Settings > Extensions > MailChimp and paste your MailChimp API key into the field "MailChimp API Key". Save changes.
6. Go to the page wp-admin > Ultimate Member > MailChimp and create a connection with the audience. Configure the connection.
7. Go to the page wp-admin > Ultimate Member > Forms > Edit Form (register) and add MailChimp field to the registration form.

Get the MailChimp API Key #

The first thing you need to do is successfully connect your site to MailChimp. To do this please do the following:

• Go to http://mailchimp.com/ and create an account or login if you already have an account.
• Once logged in click on the user icon and then click on "Account".
• On the account page click on "Extras" and select "API Keys".
• Scroll down to the "Your API Keys" section where you should see your API key (create a new key if there is no key).
• Copy API Key and paste it to the field "MailChimp API Key" on the extension`s settings page.

Image - MailChimp user menu.

Image - MailChimp "Overview" screen, the "API Keys" menu item.

Image - MailChimp "Extras" screen, the "Your API Keys" section.

Image - The site settings on  Ultimate Member > Settings > Extensions > MailChimp.

Create an audience #

For the integration between MailChimp and Ultimate Member you need to create a MailChimp audience. Please do the following:

• Click on the "Audience" in the MailChimp menu
• On the audiences page click the "Create audience" button
• On the create audience page fill in all the details and click save
• You new audience will be created

General audience settings:

• Audience name – required
• Audience ID – generated automatically
• Enable double opt-in – optional. See details here
• Enable reCAPTCHA – don't used by API
• Default From name – recommended
• Default From email address – recommended
• Default Email subject – recommended

Image - MailChimp "Audience name and campaign defaults" screen, the audience settings.

Configure settings #

Extension settings #

Once you activate the extension, you will see the tab "MailChimp" on the page  Ultimate Member > Settings > Extensions. On this page, you can find these settings:

• MailChimp API Key – The API Key copied from your MailChimp account.
• Account delete action – What to do if an account is deleted.
• Account unapprove action – What to do if the account's status is changed from "approved to" any other status.
• Groups and Tags view – A field type to display Groups and Tags in the field. (since 2.2.8)
• Enable requests cache – Cache MailChimp API requests to increase performance.
  • Cache timeout – Optional. How long to store cached requests, seconds.
• Enable requests log – Save requests to the MailChimp API into the file mailchimp.log. This information helps to configure and debug the extension.
  • Log all responses – Optional. Save responses for successful requests. The extension always saves responses for failed requests.
  • Requests log – Optional. This field displays information saved in the file mailchimp.log. You can clear or refresh the log.
• Blocked Email Addresses - A list of emails and email domains you want to block. (since 2.2.7)

Available actions on account removal and unapprove: 

• Do nothing - the contact in the audience will not be changed.
• Move to archive - the contact in the audience will be archived.
• Permanently delete - the contact will be removed from the audience forever.
• Unsubscribe member - the contact in the audience will be marked as "Unsubscribed". Recommended.

Actions "Move to archive", "Permanently delete", "Unsubscribe member" stop mailing. Be careful, the action "Permanently delete" removes a contact from the audience forever. Permanently deleted users cannot be resubscribed.

Image - The site settings on Ultimate Member > Settings > Extensions > MailChimp.

Requests log appears if Enable requests log is turned on. It displays a time, method, request path, arguments and status for each request from the extension to the MailChimp API. Requests with errors are colored in red. The extension stores responses for failed requests. The extension also stores responses for successful requests if the setting Log all responses is turned on. You may find the error detail in the RESPONSE data. This information helps to configure and debug the extension. 

You can view all requests here. You also can view important requests for a specific user by clicking View log in the column MailChimp audiences on wp-admin > Users.

User Role settings #

The extension adds settings to manage what members can edit from their accounts. Go to Ultimate Member > User Roles and choose the user role to modify. You will see the "Edit Role" page. On this page scroll down to the box "MailChimp":

• Can manage groups?
• Can manage tags?
• Can create tags?

Image - The site settings on  Ultimate Member > User Roles > Edit Role.

Create a connection #

Create a connection with the audience #

You should create a connection with the audience on your site. Do the following:

• Go to Ultimate Member > MailChimp and click the "Add New" button;
• Set the title. Select the MailChimp audience in the "Choose an audience" dropdown;
• Click the "Publish" button.

Image - The "MailChimp connections" table on  Ultimate Member > MailChimp.

Image - The "Choose an audience" dropdown on Ultimate Member > MailChimp > Add New.

General connection settings #

• Mailing audience ID – Show MailChimp audience ID.
• Enable this connection – Turn on or off this connection globally.
• Enable double opt-in* - Send contacts an opt-in confirmation email when they subscribe to your audience. This setting can enable the double opt-in feature if it isn't enabled in the audience settings. This setting is inactive if the double opt-in feature is enabled in the audience settings.
• Who can subscribe to this audience** – Select which roles can subscribe to the audience. Members who cannot subscribe to the audience don't see this audience in their accounts.
• Automatically sync contacts** – Syncs a contact on registration, profile update, role change.
• Default interests – Optional. Shown if the audience has groups. Defines group interests to automatically add a new member to these groups if the "Automatically sync contacts" option is enabled. Each group has a separate setting to select group interests.
• Default tags – Optional. Shown if the audience has tags. Defines tags to automatically add these tags to a new member if option "Automatically sync contacts" is enabled.
• Marketing Permission – Optional. Shown if audience setting "Enable GDPR fields" is enabled. (since 2.2.4)

Image - The "Setup audience" section on Ultimate Member > MailChimp > Edit MailChimp connection.

Configure fields #

Once you set up the connection and updated the page the widget "Merge User Meta" will appear. This widget syncs form fields with audience fields.

Audience fields #

The audience should be set up in a specific way to get user meta from the site. To configure conformity between fields you should create audience fields first. Do the following:

• Go to audiences and select the desired audience;
• Go to Audience > Settings > Audience fields and *|MERGE|* tags;
• You will notice that the form includes Email Address, First Name and Last Name. You can use these fields;
• Click the "Add A Field" button to add more fields. Select a field type and configure field's settings.

Image - MailChimp "Audience fields and *|MERGE|* tags" screen, the audience fields.

Merge User Meta widget #

Once you have created needed fields on your MailChimp audience go back to the connection and refresh the page. You'll see the widget Merge User Meta, that syncs form fields with audience fields. In this widget you'll see audience fields on the left and your form fields on the right. You should set relationships between these fields. Update connection to save changes when all relationships are selected.

Pay attention to required fields and choices for the "radio buttons" and "drop down" field types. Synchronization would fail if one of the required fields is empty. Synchronization may fail if values of the "radio buttons" or "drop down" field type doesn't match. 

The widget has several tools that helps you to configure fields relationship and avoid mistakes:

• required fields marked by the icon !
• information about field type and choices may be seen under the icon ?
• a warning appears under the field if configuration is wrong

Image - The "Merge User Meta" section on  Ultimate Member > MailChimp > Edit MailChimp connection.

Field type restrictions #

The address field in MailChimp is a complex field that consists of several subfields. You have to fill all required subfields or disable address field. Rules for address subfields:

There is no multi-select field type in MailChimp. Multi-select form fields can be synced with text fields. Selected options are joined to a string with comma separated values. For example the "Sports" field with multiple selected options may be synced as Football, Basketball, Tennis.
MailChimp uses the "Segment" feature to select contacts for the specific mailing campaign. You can create a segment based on the value in the text field that stores multiple values. Just use the contains rule.

Image - Segment builder with the contains rule.

Fields drop down and radio buttons can be synced if the site field choices are the same as the audience field options.

Image - How to properly configure the radio buttons field type.

We added two virtual fields to make role syncing easier. These fields can be synced with text field in the audience:

• Role slug - returns the role ID. Example: "super_editor"
• Role title - returns the role title. Example: "Super Editor"

Add MailChimp field to the registration form #

There are two ways to add a new member to the audience:

1. Members are automatically added to the audience after registration and approval if the setting "Automatically sync contacts" is enabled and setting "Who can subscribe to this audience" contains their user role;
2. Members can use a MailChimp field in the registration form to sign up for newsletters manually.

To add a MailChimp field in your registration form you have to:

• Go to wp-admin > Ultimate Member > Forms > Edit Form (Register);
• Click the "+" icon to add new field;
• Select a "MailChimp" field;
• Set the title, label and select the connection from the dropdown;
• Enable additional options if you need them:
  • Checked by default - The checkbox appears checked;
  • Manage groups - Additional field to select groups appears below the checkbox;
  • Manage tags - Additional field to select tags appears below the checkbox.
• Click the "Update" button to save changes. The field should appear in the registration form.

Examples:

Image - The "MailChimp" field options on wp-admin > Ultimate Member > Forms > Edit Form > Edit Field.

Image - The "MailChimp" field in the form builder on wp-admin > Ultimate Member > Forms > Edit Form.

Image - An example of the MailChimp field view in the registration form.

Image - An example of the MailChimp field view (with groups and tags multi-selects) in the registration form.

Image - An example of the MailChimp field view (with groups and tags checkboxes) in the registration form.

Account features #

Members can manage their newsletters on the Account page. Members can subscribe or unsubscribe, manage groups and tags (optional, depends on the role settings).

Image - The Email Newsletters section on Account > Notifications.

Error message appears if the update fails for some reason. Follow instructions in the article How to debug MailChimp error to fix a problem.

Image - Error message on Account > Notifications.

Manual syncing #

The plugin adds the MailChimp widget to the Ultimate Member dashboard. This widget displays statistical information and provides tools for manual bulk syncing:

• Bulk Subscribe & Unsubscribe
• Sync Profiles
• Update audience contacts

The tool Bulk Subscribe & Unsubscribe is used to select existing site users (by the role and the status) and manually subscribe (add) them to the audience or unsubscribe them. Users, who were added to the audience earlier, will be updated. Use it to add or remove contacts.

This tool works in two steps:

• Select role and/or status and click the "Scan now" button. Tool searches for members who match criteria and goes to the second step if members are found;
• Select the audience and click the "Subscribe" or "Unsubscribe" button.

The tool Sync Profiles updates contacts data (fields) in the selected audience and tries to recreate lost contacts. Use it to update data after adding new audience fields.

The tool Update audience contacts updates contacts data (fields) in the selected audience. This tool does not add new contacts. This tool shows information about each updated contact and error details if contact can't be updated. Use it to update fields for existing contacts.

Image - The MailChimp widget on Ultimate Member > Dashboard.