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

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

Configure connection settings #

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

Audience fields

Once you setup and publish the audience the page will refresh and the widget "Merge User Meta" will appear. This widget allows you to configure conformity between UM form fields and the audience fields.

Not all field types can be merged with MailChimp. There is no multiselect field type in MailChimp. The audience should be setup in a specific way to allow user meta to be added to the audience.

Setting up MailChimp audience for merging user meta

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.

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

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 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" used to manually subscribe (or unsubscribe) existed members to the audience. 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 the audience and click "Subscribe" or "Unsubscribe" button.

The tool "Sync Profiles" used to update members data in the selected audience. The button "Sync now" is active if there is data to sync. There are two similar tools: fast version don't show details, slow version show information about each updated contact and error details if contact can't be updated.

[Ultimate Member > Dashboard]


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