MailChimp Setup


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


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 and create an account or login if you already have an account.
  • Once logged in click on your username at top right of page and click on "Account" from the menu dropdown
  • On the account page click on "Extras" and select "API Keys"
  • Scroll down page until you come to the “Your API Keys” section where you should see your API key (If no key shows you will need to create a new key)
  • Copy this API Key and add it to the "MailChimp API Key" field on the extension`s settings page


[MailChimp > Account]

[MailChimp > Account > Extras > API keys]

[Ultimate Member > Settings > Extensions > MailChimp]

Configure extension settings #

Main settings #

  • MailChimp API Key – The API Key copied from your MailChimp account.
  • Account delete action* – What to do with subscription if the account is deleted.
  • Account unapprove action* – What to do with subscription if account's status is changed from "approved to" any other status.
  • Enable requests cache – Cache MailChimp API requests to increase performance. Enable 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 response for all requests – 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)

Note*: We don't recommend to use action "Permanently delete" because members, who were permanently deleted, cannot be resubscribed. Recommended choice - "Unsubscribe member".

[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 MailChimp audience #

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

  • Click on the "Audience" in the header menu on MailChimp
  • 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 – optional

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

Create a connection #

Create a connection with the audience #

You should create a connection with the audience on your site to allow members to subscribe to the audience. To do this please do the following:

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

[Ultimate Member > MailChimp]

[Ultimate Member > MailChimp > Add New audience]

General connection settings #

  • Connected to Mailing audience ID – Show MailChimp audience ID.
  • Enable this MailChimp audience – Turn on or off this audience globally. If enabled the audience will be available in member account page.
  • Enable double opt-in* - Send contacts an opt-in confirmation email before subscribe to the audience.
  • Audience Description in Account Page – This text will be displayed in the tab [Account > Notifications] to encourage member to sign or know what this audience is about.
  • Audience Description in Registration – This text will be displayed in the registration form if this form contains a MailChimp signup checkbox.
  • Which roles 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 the tab [Account > Notifications].
  • Automatically add new users to this audience** – If turned on members will be automatically subscribed to the audience on registration. The MailChimp signup checkbox in the registration form is hidden if this option is enabled.
  • 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 add new users to this audience" 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 add new users to this audience" 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 are automatically added to the MailChimp audience if option "Automatically add new users to this audience" is enabled and member role present in the option "Which roles can subscribe to this audience". 

The extension adds a new member to the MailChimp audience after member 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 audience]

Audience fields #

Once you setup 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.

Setup MailChimp audience fields

The audience should be setup 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. Ideally you would use a new audience for your site;
  • Go to "Manage Audience" > "Settings" > "Audience fields and *|MERGE|* tags";
  • You will notice that the form already 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.

Note: Extension can work with "radio buttons" and "drop down" fields, but sending data must be the same as MailChimp expects. Choices in the site and audience fields must be the same.
There is no multiselect field type in MailChimp.

[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 Ultimate Member audience and refresh the page. You should see MailChimp's audience fields on the left and your Ultimate Member fields on the right. You have to set relationships between these fields. Click the update button to save the changes when all relationships are selected. You can then signup as a test member or change your member`s information.

Pay attention to required fields and choices for the "radio buttons" and "drop down" field types. Synchronization between Ultimate Member and MailChimp would fail if one of the required fields is empty. Synchronization between Ultimate Member and MailChimp may fail if the value 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 !
  • additional 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 audience]

[Ultimate Member > MailChimp > Edit audience (with warning)]

Ultimate Member, MailChimp, Edit audience

Add signup checkbox to the registration form #

Ultimate Member provides two options for adding new member to the MailChimp audience:

  1. Members are automatically added to the MailChimp audience after registration and approval if the audience setting "Automatically add new users to this audience" is enabled and setting "Which roles can subscribe to this audience" contains members role;
  2. Members can select a MailChimp signup checkbox* in the registration form to sign up to the MailChimp audience.

To show the signup checkbox on your register form you need to:

  • Edit the register form;
  • Click the "+" icon to add new field;
  • Select the "MailChimp" field;
  • Set the title and select an audience 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 checkbox should appear* in the form.

* Note: The checkbox in the registration form will be hidden if the audience setting "Automatically add new users to this audience" is enabled.

[Ultimate Member > Forms > Edit Form]

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

[Registration page]

[Registration page with additional options] (since 2.2.5)

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 update fails for some reason. Verify your audience settings in the MailChimp and WordPress. Pay attention to "Merge User Meta", especially on required fields and choices for the "radio buttons" and "drop down" field types.

[Account page > Notifications]

Syncing between the site and MailChimp #

The plugin adds the MailChimp widget to the Ultimate Member dashboard. This widget contains several useful 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 MC audience or unsubscribe them. Users, who were added to the MC 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 MC 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]

Related articles:
How to debug MailChimp error
Registration with MailChimp double opt-in