MailChimp Setup

Overview

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

Contents

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

[MailChimp]

[MailChimp > Account]

[MailChimp > Account > Extras > API keys]

[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

[MailChimp > Audience > Settings > Audience name and defaults]

Configure extension settings #

Main settings #

A list of 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 – How long to cache MailChimp API requests, seconds.
  • Enable requests log – Save requests to the MailChimp's server into the file mailchimp.log. Requests log is used to debug MailChimp API issues.
  • Log all responses – Save responses for successful requests. Requests log always saves responses for failed requests.
  • Requests log – Show and clear the file mailchimp.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".

Actions "Move to archive", "Permanently delete", "Unsubscribe member" stop mailing, but only the action "Permanently delete" removes a contact from the audience. Recommended choice - "Unsubscribe member".

* Note: Permanently deleted users can not be resubscribed.

[Ultimate Member > Settings > Extensions > MailChimp]

User role settings #

Each user role has settings that manage what a member can edit from the account page. (since 2.2.4)

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

[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 the menu [Ultimate Member > MailChimp] and click the button "Add New";
  • Set the title. Select the MailChimp audience in the dropdown "Choose an audience";
  • Click the "Publish" button.

[Ultimate Member > MailChimp]

[Ultimate Member > MailChimp > Add MailChimp connection]

General connection settings #

  • Connected to Mailing audience ID – Show MailChimp audience ID.
  • Enable this connection – Turn on or off this audience globally.
  • Enable double opt-in* - Send contacts an opt-in confirmation email before subscribing to the audience. This setting enables double opt-in if it is not enabled in the audience settings.
  • A label in the Account page – This text will be displayed in the account to encourage members to sign or know what this audience is about.
  • A label in the Registration form – This text will be displayed in the registration form if this form contains a MailChimp field.
  • 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 group "..." interests – optional, shown only if the audience has groups. Allow to define group interests and automatically add a member to these groups (if option "Automatically sync contacts" is enabled).
  • Default tags – optional, shown only if the audience has tags. Allow to define tags and automatically attach these tags to a new member (if option "Automatically sync contacts" is enabled).
  • Marketing Permission – optional, shown only if audience setting "Enable GDPR fields" is enabled. (since 2.2.4)

* Note: MailChimp adds a new member to the audience after the email confirmation if the option "double opt-in" is enabled.

** Note: Registered members will be added to the MailChimp audience automatically if option "Automatically sync contacts" is enabled and their user role was selected in the option "Who can subscribe to this audience". 

The extension adds new members to the MailChimp audience after approval. The extension doesn't add a new member if the member's status is pending admin or email verification until this member will be approved.

[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 allows you to configure conformity between UM form fields and the 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 button "Add A Field" to add more fields. Select a field type and configure field's settings.

[MailChimp > Audience > Settings > Audience fields and *|MERGE|* tags]

Merge User Meta widget #

Once you have created all of the 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

[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:

Subfield Required Recommendation  Example
Street Address Yes Must be merged with the required text field in the registration form 20 W 34th St
Address line 2 No Should be merged with the optional text field in the registration form next floor 
City Yes Must be merged with the required text field in the registration form New York
State/Prov/Region Depends on country It is empty or text if there are no states in the country. It is a code of the state if the country has states. NY
Postal/Zip Yes Must be merged with the required text field in the registration form 10001
Country Yes Must be merged with the required dropdown field that contains country codes US

There is no multi-select field type in MailChimp. Multi-select form fields can be synced with text fields. Selected options will be separated by commas.

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"
Fields drop down and radio buttons can be synced if the site field choices are the same as the audience field options. See example:

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 the [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 (since 2.2.5):
    • 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.
  • Update the field and the form. Look at the registration form on the front-end. The field should appear in the form.

[Ultimate Member > Forms > Edit Form]

[Ultimate Member > Forms > Edit Form > Edit Field]

[MailChimp field in the registration form]

[MailChimp field with options as multi-selects in the registration form] (since 2.2.5)

[MailChimp field with options as checkboxes in the registration form] (since 2.2.8)

Manage newsletters from Account page #

Each member can manage newsletters on the Account page. Members can subscribe or unsubscribe, manage groups and tags (optional).

[Account page > Notifications]

Error message appears if the update fails for some reason. Verify your audience settings in the MailChimp and connection settings WordPress. Pay attention to "Merge User Meta" widget, especially on required fields and warnings.

[Account page > Notifications]

Manual syncing #

The plugin adds the MailChimp widget to the Ultimate Member dashboard. This widget contains several tools that help you manage a lot of contacts at once.

  • Bulk Subscribe & Unsubscribe
  • Sync Profiles (fast)
  • Sync Profiles (with details)

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

Tools  Sync Profiles are used to update members data (fields) in the selected audience. These tools don't add new contacts to the audience. These tools may be used to update data after adding/changing audience fields. There are two similar tools: fast and slow. The fast version doesn't show details. The slow version shows information about each updated contact and error details if contact can't be updated. The button "Sync now" is active if there is data to sync.

So, in a simple words:

  • use the tool "Bulk Subscribe & Unsubscribe" to add/update contacts;
  • use the tool "Sync Profiles" to update fields.

[Ultimate Member > Dashboard]