MailChimp Setup


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


Configure extension settings #

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

  • On the account page click on "Extras" and select "API Keys"

[MailChimp > Account]

  • 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)

[MailChimp > Account > Extras]

  • Copy this API Key and add it to the "MailChimp API Key" field on the extension`s settings page

[Ultimate Member > Settings > Extensions > MailChimp]

Extra settings

  • Verify nonce when user subscribed – Enables nonce verification for manual subscribe at registration. Warning: this tool may conflict with caching plugins.
  • Enable double opt-in – Send members an opt-in confirmation email when subscribing to the audience. Details
  • 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

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]

Create a MailChimp audience #

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

  • Click on audiences 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 then be created

Adding an audience on your site #

To allow members on your site to subscribe to this MailChimp audience you need to create a MailChimp audience on your site also. To do this please do the following:

  • Go to MailChimp in the Ultimate Member menu and click “Add New audience” button
  • Give the audience a title
  • Select your MailChimp audience from the Choose a audience dropdown (If you have successfully connected to MailChimp via API key you will see your MailChimp audiences in the dropdown)
  • Click "Publish" button

[Ultimate Member > MailChimp]

[Ultimate Member > MailChimp > Add New audience]

Configure audience 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 when they subscribe to your audience.
  • Audience Description in Account Page – This text will be displayed in Account > Notifications to encourage member to sign or know what this audience is about.
  • Audience Description in Registration – This text will be displayed in register form if you enable this mailing audience to be available during signup.
  • Which roles can subscribe to this audience – Select which roles can subscribe to this audience. Members who cannot subscribe to this audience will not see this audience on their account page.
  • Automatically add new users to this audience* – If turned on members will automatically be subscribed to this when they register. When turned on this audience will not show on register form even if you add MailChimp field to register form.
  • Default group "..." interests - optional, shown only if audience has a group. Allow to predefine group interests and automatically add new member to these groups (if option "Automatically add new users to this audience" is enabled).
  • Default tags - optional, shown only if audience has a tag. Allow to predefine tags and automatically attach these tags to a new member (if option "Automatically add new users to this audience" is enabled).

Note: New registered member is 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". 
Extension adds new member to the MailChimp audience after member approvement. It depends on role option "Registration Status".

[Ultimate Member > MailChimp > Edit audience]

Merge user meta

Once you have setup the audience and clicked the "Publish" button the page will refresh and a new widget will appear called “Merge user meta”.

Merge user meta allows you to add a member`s meta to your MailChimp audience. Not all field types can be merged with MailChimp. The MailChimp audience must also be setup in a specific way to allow user meta to be added to the MailChimp audience.

Setting up MailChimp audience for merging user meta

To configure audience merge data relationship you need to create audience fields first. To do this please 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 leave these as they are
  • You are going to use the form builder to add additional fields to your audience and these fields will be how you merge user meta to your audience

Note: Extension can work with "radio buttons" and "drop down" fields, but sending data must be the same, as MailChimp expects. Even one wrong symbol (such as space or dot) may cause an error.

[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 will then see a audience of all of your Ultimate Member fields on the left. You then need to select the mailchimp field from the dropdown on the right that you want to sync to.

[Ultimate Member > MailChimp > Edit audience]

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.

[Ultimate Member > MailChimp > Edit audience]

Ultimate Member, MailChimp, Edit audience

After you have selected the fields you want to merge into the MailChimp audience click the update button to save the changes. You can then signup as a test member or change your member`s information.

Syncing between your site and MailChimp #

The plugin provides tools "Sync Profiles" and "Bulk Subscribe & Unsubscribe" which you will find on the MailChimp widget on the Ultimate Member dashboard.

"Sync Profiles" tool allow manually sync to MailChimp when you click the "Sync now" button. "Sync now" button is active if there is data to sync.

You also may manually subscribe existed members to the audience using "Bulk Subscribe & Unsubscribe" tool. This tool works in two steps:

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

[Ultimate Member > Dashboard]

Add audience 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 when they register if audience`s option "Automatically add new users to this audience" is enabled
  2. Members can select a checkbox on register form to signing up to the MailChimp audience(s). 

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

  • Edit the register form
  • Click + icon to add new field
  • Select MailChimp field
  • Give the field a title and select the audience you want to add from the dropdown
  • Update form and check register form on front-end. The MailChimp signup audience should now appear on the form

Note: MailChimp signup checkbox in the registration form will be hidden if audience`s option "Automatically add new users to this audience" is enabled.

[Ultimate Member > Forms > Edit Form > MailChimp field]

[Registration page]

Manage newsletters from Account page #

Each member can manage newsletters on Account page. Member can subscribe or unsubscribe, add or remove group interests and tags.

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

How to debug errors

Please read article How to debug MailChimp error.