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, automation and campaigns if you're new to MailChimp.
Contents
- Getting started
- Get the MailChimp API Key
- Create an audience
- Configure settings
- Create a connection
- Configure behavior on registration
- Account features
- Manual syncing
Getting started #
Main steps to configure the extension:
- Go to MailChimp and create an account.
- Create a MailChimp audience.
- Copy MailChimp API key.
- Go to your site and install the MailChimp extension.
- Go to wp-admin > Ultimate Member > Settings > Extensions > MailChimp and paste your API key into the field "MailChimp API Key".
- Go to wp-admin > Ultimate Member > MailChimp and create a connection. Configure the connection.
- Go to wp-admin > Ultimate Member > Forms > Edit Form to 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 it into 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 | Description |
|---|---|
| Audience name | Required |
| Audience ID | Generated automatically |
| Enable double opt-in | Optional. See details here |
| Enable reCAPTCHA | Not used by the 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:
| Setting | Description |
|---|---|
| MailChimp API Key | This field requires you to input the API Key copied from your MailChimp account. The MailChimp API key allows Ultimate Member syncing your user data with your MailChimp audiences. This integration helps automate email marketing and user management directly within your WordPress site. |
| Account delete action | Specifies what action to take when a user account is deleted:
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. |
| Account unapprove action | Specifies what action to take when an account's status is unapproved or deactivated. Options are the same as for the "Account delete action" setting. |
| Groups and Tags view | Defines how to display Groups and Tags in the user profile field. You can choose from the following display options:
|
| Enable language field | Allows members to select their preferred language for receiving newsletters. When enabled, an additional option Default language will appear. |
| Default language | You can select the default language from the dropdown list, with English as the default option. This ensures members receive newsletters in their preferred language. |
| Enable requests cache | Improves performance by caching MailChimp API requests, reducing the need for repeated calls to the API. This setting must be enabled to access the Cache timeout option. |
| Cache timeout, s | (Optional) Specifies how long cached API requests should be stored, in seconds. The default value is 600 seconds (10 minutes). A longer timeout reduces API calls but may delay updates to MailChimp data. |
| Enable requests log | Saves detailed information about all requests and responses sent to the MailChimp API. This feature is useful for configuring and debugging the extension. Enabling this option reveals the Requests log. |
| Requests log | (Optional) Displays the log of API requests and responses. The log includes filtering and search functionality to find specific entries. You can also clear or refresh the log as needed. |
| Blocked Email Addresses | Specify a list of email addresses and domains that you want to block from being added to the audience. Add each email or domain on a new line. Addresses listed here cannot be added to the audience, and existing contacts will be unsubscribed during the next update if automatic sync is enabled. To block an entire domain, use a wildcard format such as *@domain.com. |
Requests log #
The requests log appears if the Enable requests log setting is turned on. It displays the time, status, method, request path, arguments, and referrer for each request to the MailChimp API. The extension stores a response for requests with error.
You can find the error details in the RESPONSE data. This information helps to configure and debug the extension.
You can search in the log and filter requests using the following dropdown options:
- All requests - View all recorded requests.
- Only requests with error - View only the requests that encountered an error.
- Only requests to add or update - View requests related to adding or updating records.
Additionally, you can view important requests for a specific user by clicking View log in the MailChimp column 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.
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 connection title. This title is displayed next to the checkbox in forms.
- 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 #
| Setting | Description |
|---|---|
| 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 won't see this audience in their accounts. |
| Automatically sync contacts ** | Syncs a contact on registration, profile update, or 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 the "Automatically sync contacts" option is enabled. |
| Default tags for existing contacts | How to apply default tags when updating existing contacts. |
| Marketing Permission | Optional. Shown if the audience setting "Enable GDPR fields" is enabled. |
Image - The Setup audience section on wp-admin > Ultimate Member > MailChimp > Edit MailChimp connection.
Configure fields #
Once the connection is set up and the page is reloaded the Merge User Meta section appears. In this section you can merge your form fields with audience fields.
Audience fields #
Create fields you need in your MailChimp audience first. Do the following:
- Enter your MailChimp account.
- Go to Audience > Settings > Audience fields and merge tags.
- You will see a table with existing audience fields. Click the Create a new field button to add more fields.
- You will see the Create a new field popup. Enter the field label, select a field data type, enter merge tag.
- Click the Save button to save a field.
Image - Audience fields and merge tags screen.
Image - Create a new field popup.
Merge User Meta widget #
Once needed audience fields are created go back to the connection and refresh the page. You'll see fields in the Merge User Meta section. Audience fields are shown on the left and form fields are shown on the right. You should set relationships between audience fields and your website form fields. Click the Update button to save changes.
Image - The Merge User Meta section on wp-admin > Ultimate Member > MailChimp > Edit MailChimp connection.
Pay attention to the 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 the values of the "radio buttons" or "drop-down" field type doesn't match.
The widget has tools that help you to 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 the configuration is wrong
Field type restrictions #
The address audience field is a complex field that consists of several subfields. You have to fill all required subfields or disable address field. Rules for address subfields:
| Subfield | Required | Recommendation | Example |
|---|---|---|---|
| Street Address | Yes | Must be merged with the required text field in the registration form | 20 W 34th St |
| Address line 2 | No | Should be merged with the optional text field in the registration form | next floor |
| City | Yes | Must be merged with the required text field in the registration form | New York |
| State/Prov/Region | Depends on country | It is empty or text if there are no states in the country. It is a code of the state if the country has states. | NY |
| Postal/Zip | Yes | Must be merged with the required text field in the registration form | 10001 |
| Country | Yes | Must be merged with the required dropdown field that contains country codes | US |
The dropdown and radio button fields can be synced with corresponding form fields (Dropdown and Radio) if the form field choices match the options in the audience field. However, we do not recommend using these field types, as synchronization can break if an option is added or removed on one side but not the other. It’s better to sync Dropdown and Radio form fields with a text audience field.
The text audience field also can be merged with the multi-select form field. In this case multiple values are combined into a string, with each value separated by a comma. For example, a "Sports" field with multiple values could be synced as "Football, Basketball, Tennis". It is possible to create a segment based on the value stored in the text field containing multiple values. Use the contains rule to match the desired value.
Image - The Segment builder with the contains rule.
To simplify role syncing, we've added two virtual role fields that can be synced with a text field in the audience:
- Role slug - Returns the role ID.
- Role title - Returns the role title.
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 the new field.
- Select the MailChimp field.
- Set the title and label, then 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 - An additional field to select tags appears below the checkbox. Default tags are used if disabled.
- Manage language - If enabled, this option allows users to select and manage their preferred language from their account form.
- Checkbox label - This setting allows you to customize the label text for the MailChimp checkbox field. You can modify the default label to better suit your form's needs or provide more specific instructions for users.
- 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, and manage groups and tags (optional, depends on the role settings).
Image - The Email Newsletters section on Account > Notifications.
An error message appears if the update fails for some reason. Follow the 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 syncing and importing.
Bulk Subscribe or Unsubscribe
This tool is used to select existing site users (by role and status) and manually subscribe (add) them to the audience or unsubscribe them. Users who were previously added to the audience will have their data updated. You can also use this tool to add or remove contacts.
Steps:
- Select role and/or status and click the "Scan now" button. The tool searches for members matching the criteria and proceeds to the next step if members are found.
- Select the audience and click "Subscribe" or "Unsubscribe".
Update Audience Contacts
This tool updates contact data (fields) in the selected audience. This tool does not add new contacts. It shows detailed results for each updated contact, including error details if a contact update fails. Use this tool to ensure existing contact fields are up-to-date.
Import Users from MailChimp
This tool allows you to import users from your MailChimp audience into your website. Just select a connection, set importing options and click the Run import button. This tool is available since version 2.5.0.
| Option | Description |
|---|---|
| Select Connection | Choose a specific MailChimp audience to import contacts from, ensuring the correct subscribers are added or updated. |
| Import Only "Subscribed" Contacts | Restrict the import to MailChimp contacts with a "subscribed" status to maintain a clean and relevant user base. |
| Update Existing Users | Update data for users already present on your site based on MailChimp information. |
| Create New Users | Add new users to your site using data from MailChimp subscribers. |
Image - The MailChimp widget on wp-admin > Ultimate Member > Dashboard.
Bulk subscribe for newsletters from the Users table #
The plugin adds a tool used to bulk update the MailChimp subscription status (subscribed or unsubscribed) to the Users page. You can also use this tool to manually add new contacts to the audience, but this is limited by the connection settings for allowed roles.
This tool works like bulk actions. Select the users you want to update, select a connection, click a button.
Image - Bulk Subscribe on wp-admin > Users.
