MailChimp Setup

Overview

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

Contents

Configure extension settings #

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

[MailChimp > Account]

[MailChimp > Account > Extras > API keys]

[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. (since 2.2.4)
  • Account unapprove action* – What to do with subscription if account's status is changed from "approved to" any other status. (since 2.2.4)
  • 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 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
  • Enable GDPR fields – optional
  • Enable reCAPTCHA – don't used by API
  • From name Default – recommended
  • Default From email address – recommended
  • Default Email subject – optional

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

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 the "Publish" button

[Ultimate Member > MailChimp]

[Ultimate Member > MailChimp > Add New audience]

Configure audience settings #

General 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 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 audience has a tag. 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]

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. Choices in the UM field must match to choices in the MailChimp field.

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

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]

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]

How to debug errors

Please read article How to debug MailChimp error.