MailChimp Setup

Overview

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

The extension adds contacts to your MailChimp audience when users register on your website. Once you have contacts with data you can start segmenting your audience and create automations or campaigns. Read MailChimp documentation about segmenting, automations and campaigns if you're new to MailChimp.

Contents

• Getting started
• Get the MailChimp API Key
• Create an audience
• Configure settings
  • Extension settings
    • Account delete action
    • Requests log
  • 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
• Configure behavior on registration
• Account features
• Manual syncing
  • Sync from the dashboard widget
  • Bulk subscribe for newsletters from the Users table

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 wp-admin > Ultimate Member > Settings > Extensions > MailChimp and paste your MailChimp API key into the field "MailChimp API Key". Save changes.
6. Go to wp-admin > Ultimate Member > MailChimp and create a connection with the audience. Configure the connection.
7. Go to wp-admin > Ultimate Member > Forms > Edit Form (register) and add the MailChimp field to the registration form if needed.

Get the MailChimp API Key #

Follow these steps to create your MailChimp account and get your MailChimp API key:

• Go to the MailChimp website and create an account or login if you already have an account.
• Click the user icon to open the user menu then click the Account and billing item.
• On the account page click the Extras menu item then click the API keys subitem.
• Scroll down to the Your API Keys section and click the Create A Key button.
• Enter the API Key Name and click the Generate Key button.
• Copy your API key and click the Done button.

Once you have an API key go to your website and paste your API key to the MailChimp API Key setting on wp-admin > Ultimate Member > Settings > Extensions > MailChimp.

Image - MailChimp user menu.

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

Image - Extras screen, the Your API Keys section.

Image - Name New API Key screen.

Image - Copy New API Key screen.

Image - The MailChimp API Key setting on wp-admin > 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 the "Audience" item in the MailChimp menu.
• On the audiences page click the "Create audience" button. MailChimp allows you to create the first audience for free. The "Create audience" button is hidden if you reached a limit of audiences allowed for your plan.
• 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 - Audience name and campaign defaults screen, the audience settings.

Configure settings #

Extension settings #

Once you activate the extension, you will see the MailChimp tab on the page wp-admin > Ultimate Member > Settings > Extensions. On this tab, 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.
• Enable requests cache – Cache MailChimp API requests to increase performance.
  • Cache timeout – Optional. How long to store cached requests, seconds.
• Enable requests log – Save information about requests and responses to the MailChimp API. This information helps to configure and debug the extension.
  • Log all responses – Optional. Save responses for all requests. The extension always saves responses for failed requests.
  • Requests log – Optional.This field displays saved information. You can clear or refresh the log.
• Blocked Email Addresses - A list of emails and email domains you want to block.

Image - Settings on wp-admin > Ultimate Member > Settings > Extensions > MailChimp.

Account delete action #

Available actions on account delete and account 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.

Warning: The "Permanently delete" action removes a contact from the audience forever. Permanently deleted users cannot be resubscribed. Don't use this if you're not sure.

Requests log #

Requests log appears if the Enable requests log setting is turned on. It displays a time, status, method, request path, arguments and referrer for each request to the MailChimp API. The extension stores a response for failed requests by default. The extension stores a response for all requests if the Log all responses setting is turned on.

You can find the error detail in the RESPONSE data. This information helps to configure and debug the extension.

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

User Role settings #

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

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

Image - Settings on wp-admin > Ultimate Member > User Roles > Edit Role.

Create a connection #

Create a connection with the audience #

Follow these steps to create a connection with the audience:

• Go to wp-admin > Ultimate Member > MailChimp and click the Add New button.
• Set the title. 
• Select the MailChimp audience in the Choose an audience dropdown.
• Click the Create button.

Image - The MailChimp connections table on wp-admin > Ultimate Member > MailChimp.

Image - The Choose an audience dropdown on wp-admin > 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 interests for existing contacts – How to apply default interests when updating existing contacts.
• 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.
• Default tags for existing contacts – How to apply default tags when updating existing contacts.
• Marketing Permission – Optional. Shown if audience setting "Enable GDPR fields" is enabled.

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

Configure fields #

Once you set up the connection and updated the page the  Merge User Meta section 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 data from the site. You have to 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.
• Save Changes.

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

Merge User Meta widget #

Once you create needed audience fields go back to the connection and refresh the page. You'll see the widget Merge User Meta, that syncs form fields with the audience fields. In this widget audience fields are shown on the left and form fields are shown on the right. You should set relationships between audience fields and form fields created on your site. Click the Update button to save changes.

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 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 wp-admin > 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 - The Segment builder with the contains rule.

The drop down and radio buttons fields in MailChimp can be synced with Dropdown and Radio form fields if the form field choices are the same as the audience field options. We don't recommend using these field types because synchronization stops working if you add/remove an option on the one side and forget to do the same on the other side. It's better to sync Dropdown and Radio form fields with the text audience field.

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

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

Configure behavior on registration #

There are two ways to handle members on registration:

• Auto - Members are added to the audience after registration and approval if the Automatically sync contacts setting is enabled and their user role is selected in the Who can subscribe to this audience setting. A field in the registration form is non needed to use Auto mode.
• Manual - Add the MailChimp field to the registration form to allow members to sign up for newsletters manually. This field is visible in the registration form if the user role assigned on registration is selected in the Who can subscribe to this audience setting.

Follow these steps to add a field to the registration form:

• Go to wp-admin > Ultimate Member > Forms > Edit Form (Register).
• Click the "+" icon to add new field.
• Select the 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. Default groups are used if disabled.
  • Manage tags - Additional field to select tags appears below the checkbox. Default tags are used if disabled.
• Click the Update button to save changes. The field should appear in the form.

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

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

Account features #

Members can manage their newsletters in the account tab Notifications. 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 #

Sync from the dashboard widget #

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 or Unsubscribe
• Sync Profiles
• Update audience contacts

The tool Bulk Subscribe or 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 wp-admin > Ultimate Member > Dashboard.

Bulk subscribe for newsletters from the Users table #

The plugin adds tools for bulk Subscribe or Unsubscribe to the Users table. These tools work like bulk actions. Select users you want to update, select a connection, click a button.

Image - Bulk Subscribe on wp-admin > Users.