Mailchimp is a web based email marketing service used to send mass emails to a list of subscribers.
Drupal, out of the box, already allows you to send emails. However, there are distinct advantages to using a service like Mailchimp to send emails and maintain your mailing lists.
In this tutorial, you’ll learn how to integrate Drupal and Mailchimp.
The Mailchimp module integrates Mailchimp and Drupal by allowing Drupal to connect via Mailchimp’s API. This module also comes with a few submodules. Each submodule provides additional functionality that leverages Mailchimp’s features.
These submodules are:
- Mailchimp Lists
- Mailchimp Campaign
- Mailchimp Signup
This tutorial will cover each of these submodules in more detail.
First make sure you have a Mailchimp account. Just go to mailchimp.com and create a free account.
It is recommended to install this module using Composer so that the Mailchimp API library will be automatically downloaded to the correct location:
composer require drupal/mailchimp
To enable the module: we can use Drush:
drush en mailchimp -y
After enabling any Drupal module, it’s a good idea to clear the Drupal cache:
Now go to Configuration >> Web Services >> Mailchimp (admin/config/services/mailchimp)
Here you need to enter your Mailchimp API key. The initial configuration screen looks like this:
You will notice the error:
“Failed to load Mailchimp PHP library. Please refer to the installation requirements.”
This is because you have not entered your Mailchimp API key yet. To get your Mailchimp API key, log into your MailChimp account and go to Account >> Extras >> API Keys.
Create your API key and insert it in the Drupal Mailchimp API key field as shown in the above screenshot and then click on “Save configuration”.
You may need to refresh the page to suppress the error.
At this point, you have successfully linked your Drupal site to the Mailchimp API.
Using the Mailchimp Lists
A Mailchimp List is also known as “Audience” within the Mailchimp interface. It seems Mailchimp uses the terms “List” and “Audience” interchangeably within their interface.
The Mailchimp Lists submodule allows you to subscribe any entity with an email address to Mailchimp Lists by creating a Mailchimp List field and allowing anyone who can edit that type of entity to subscribe/unsubscribe and update member information directly from within Drupal.
So what does this mean? In a nutshell, it allows you to connect your Mailchimp Audience to Drupal.
Then, any Drupal entity with an email field (typically the User entity) can be used to subscribe users to your Mailchimp Audience. The process of “subscribing users” is done by the Mailchimp Signup submodule, which is explained further in this tutorial.
The Mailchimp List submodule only connects your Mailchimp Audience to Drupal so that Drupal is aware of all your Mailchimp Audiences.
Step 1: In Mailchimp go to “Audience” and create your Audience/List. For this tutorial, we have created a Mailchimp audience with the name “Webwash Test Audience”.
NOTE: You can only create a single audience using a free account.
Step 2: Use Drush to enable Mailchimp Lists in Drupal:
drush en mailchimp_lists -y
Step 3: Clear the Drupal cache:
At this point, in Drupal if you go to Configuration >> Web services >> Mailchimp >> Audiences (admin/config/services/mailchimp/lists) you should see all of your Mailchimp lists which looks like this:
To allow Drupal users to be added to this List, go to the “Signup forms” section of your Mailchimp Audience as shown in the screenshot below:
There are a few options on this page to embed the form into your Drupal site, which mostly involves creating and editing the form from within the Mailchimp interface and then embedding the generated HTML code directly into a Drupal block or page template.
You can also use the Mailchimp Signup submodule, which creates a block or page with a simple web form with fields such as Email (required), First Name and Last Name etc. When users submit this form, they will be subscribed to your Mailchimp list.
Now that you have connected your Mailchimp Audience (List) to Drupal, you can allow users to subscribe to your Mailchimp list within Drupal.
How do you do this? You have to use the Mailchimp Signup submodule.
Using the Mailchimp Signup
The Mailchimp Signup submodule allows you to create blocks and/or pages within your Drupal site to allow users to subscribe to Mailchimp Lists. This way, you do not have to embed any Mailchimp generated code into your site.
We will now demonstrate how you can use this module.
Step 1: Enable the Mailchimp Signup submodule using Drush:
drush en mailchimp_signup -y
Step 2: Clear the Drupal cache:
Go to Configuration >> Web services >> Mailchimp you will notice a new tab “Signup Forms” as shown below. The direct Drupal URL is:
Step 3: Add a Signup Form
Click on “Add Signup Form” and fill in the details. For this tutorial we will select both Block and Page for demonstration purposes. This is a screenshot of our Signup form:
Notice that the Mailchimp Audience is automatically available (thanks to the Mailchimp List submodule).
In the Merge Field Display section, you will see the fields that are generated from your Mailchimp form. You can edit these fields by going to the Settings of your Audience in Mailchimp and then under Settings, click on “Audience fields and *|MERGE|* tags” as shown below:
If you selected Page Display mode, you can go to the URL you entered and your sign up form should look like this:
For the Block Display mode, you must clear the Drupal cache first and then you can add the block to any region in the usual Drupal way by going to Structure >> Block layout and placing the block in the desired region. We have placed our block in the right sidebar region of our homepage and it looks like this:
NOTE: If you go to Structure >> Block layout and you do not see the Sign up block when trying to place it in a region, you should clear your Drupal cache.
It is worth mentioning that the Mailchimp Signup module comes with some permissions as shown below. You can set this to your liking:
Using the Mailchimp Campaigns
The Mailchimp Campaign submodule allows Drupal users (with the appropriate permissions) to send Mailchimp campaigns from within Drupal. The content of the campaigns can contain any Drupal entity or custom HTML content.
We will demonstrate how to set up Mailchimp Campaigns from within Drupal.
Step 1: Enable the Mailchimp Campaigns submodule using Drush:
drush en mailchimp_campaign -y
Step 2: Clear the Drupal cache:
Step 3: Set the appropriate permissions.
The Mailchimp Campaign submodule comes with 1 permission allowing a specified role to administer Mailchimp Campaigns from within Drupal (see screenshot below). You should set this permission to the appropriate role.
Step 4: Create at least 1 Audience Tag
As of March 21st 2021, there is a reported bug whereby if you do not have any Audience Tags defined for your Audience, you will not be successful in creating a campaign in Drupal. Follow the bug here. A temporary workaround is to create at least 1 Audience Tag in Mailchimp.
So let’s create an Audience Tag in Mailchimp. In Mailchimp, there are two ways to add Audience Tags. You can either click on the Tags menu in the left sidebar for your Audience, or find the Tags setting under “Manage Contacts”. Both options are shown in the screenshot below:
Go ahead and create a tag. Even though we are not using this Tag for our Campaign, we need at least 1 Tag created until the bug has been fixed.
When this bug is fixed, Step 4 will no longer be required.
Step 5: Add your Mailchimp Campaign within Drupal
There are two ways to add Mailchimp Campaigns. One way is from within the Mailchimp interface (hereby bypassing the need for this module) and another is using this module and doing it inside of Drupal. It is important to note that if you create a campaign from within Mailchimp, it will not be imported into Drupal. However, the reverse is not true. That is, if you create a campaign from within Drupal, it will be automatically imported into Mailchimp.
To create your campaign within Drupal, go to Configuration >> Web services >> Mailchimp and click on the Campaigns tab. Then click on “Add Mailchimp Campaign”. This is shown below:
Fill in all the necessary fields. Notice that the Audience Tags field is automatically prefilled once you select the Audience as shown below:
NOTE: At the time of writing this tutorial (March 21st 2021), if you try to create a Campaign from within Drupal, it will only work if you do not select a template as shown below.
Whatever you type into the “Content” field will be inserted into the email body when you send the Campaign. Follow this issue to keep updated when there is a fix.
Once you create your Campaign in Drupal, it will look similar to this:
And your Campaign will be automatically imported into Mailchimp which will look like this:
Mailchimp and Drupal can be connected to integrate Mailchimp’s features in Drupal. We have shown how to use the Mailchimp module to do this.
The Mailchimp List submodule can be used to connect your Drupal entities to a Mailchimp Audience.
Once connected you can then use the Mailchimp Signup submodule to provide a page/block for Drupal users to actually sign up and be added to your Mailchimp Audience.
And finally the Mailchimp Campaign submodule can be used to create Campaigns within Drupal.