Mailchimp
Provides integration with the Mailchimp email delivery service, enabling audience management, subscription forms, campaign creation, and behavioral event tracking from within Drupal.
mailchimp
Install
composer require 'drupal/mailchimp:^3.1'
composer require 'drupal/mailchimp:^2.2'
Overview
The Mailchimp module provides comprehensive integration with the Mailchimp email delivery service. While tools for sending email from your own server exist, they lack the sophistication and ease of use of dedicated email providers like Mailchimp.
The core module provides basic configuration and API integration, while features and site functionality are provided by a set of submodules. These submodules enable anonymous signup forms, entity-based audience subscriptions, campaign creation and sending, and behavioral event tracking for marketing automation.
Key capabilities include OAuth authentication (recommended) or API key authentication (deprecated), support for unlimited audiences, merge field mapping, interest groups, Connected Sites integration, webhook handling for real-time synchronization, and cron-based batch processing for subscription operations.
Features
- API integration with Mailchimp using OAuth authentication (recommended) or API key (deprecated)
- Support for unlimited Mailchimp audiences (mailing lists)
- Anonymous signup forms displayed as blocks or standalone pages for any combination of audiences
- Entity-based audience subscription via custom field types, allowing subscription rules to follow entity permissions and controls
- User subscription during registration by adding a Mailchimp Subscription field to Users
- Mapping of Drupal entity field values to Mailchimp merge fields
- Standalone subscribe and unsubscribe forms with merge field and interest group support
- Subscription maintenance via cron batch processing or real-time updates
- Create and send Mailchimp campaigns directly from Drupal using entity content
- Behavioral event tracking for Mailchimp's automated campaigns
- Webhook integration for real-time synchronization of subscription changes from Mailchimp
- Connected Sites integration for embedding Mailchimp JavaScript and popup forms
- GDPR consent checkbox support for signup forms
- Integration with ECA (Entity Control Actions) module for automation workflows
- Webform handler for triggering Mailchimp events on form submissions
Use Cases
Newsletter Subscription for Website Visitors
Create anonymous signup forms using Mailchimp Signup submodule. Display forms as blocks in sidebars or footers, or as standalone pages like /newsletter. Configure merge fields to collect additional information like name or preferences, and enable interest groups to let subscribers choose content categories. Use GDPR consent checkbox for compliance.
User Registration with Audience Subscription
Add a Mailchimp Subscription field to the User entity type using Mailchimp Audiences submodule. Users can subscribe during registration or manage their subscription from their profile. Map user profile fields (name, location, etc.) to Mailchimp merge fields for personalized email content.
Role-Based Automatic Subscriptions
Use Rules or ECA integration to automatically subscribe users to specific audiences based on their roles. Create a hidden Mailchimp Subscription field on Users and configure automation rules to subscribe members when they are assigned particular roles (e.g., Premium Members audience for premium role).
Email Campaigns with Drupal Content
Use Mailchimp Campaign submodule to create email campaigns that include Drupal content. Import articles, products, or any entity with a title into campaign templates using the entity import feature. Select specific view modes to control how content appears in emails.
Behavioral Targeting for E-commerce
Use Mailchimp Events submodule with Webform integration to track user behavior. Create events like 'completed_purchase' or 'abandoned_cart' that trigger automated email sequences in Mailchimp. Pass order details or product information as event properties for personalized follow-up emails.
Real-Time Subscription Synchronization
Configure webhooks to keep Drupal synchronized with Mailchimp. When users unsubscribe or update their profiles directly in Mailchimp (e.g., via email preferences link), the webhook updates the cached subscription data in Drupal, ensuring accurate subscription status display.
Multi-Audience Subscription Forms
Create signup forms that allow subscription to multiple audiences simultaneously. Useful for organizations with different newsletter types (e.g., News, Events, Promotions) where visitors can select which communications they want to receive.
Connected Sites with Popup Forms
Enable Connected Sites to embed Mailchimp's JavaScript on specific pages. This allows use of Mailchimp's popup subscription forms that can be designed in Mailchimp and triggered based on user behavior (time on page, scroll depth, exit intent).
Tips
- Use OAuth authentication instead of API keys - API key authentication is deprecated and OAuth provides better security
- Configure webhooks to keep Drupal synchronized when users modify their subscriptions through Mailchimp directly
- Use batch processing for sites with many subscribers to avoid timeout issues, but be aware that changes won't appear until cron runs
- The Connected Sites feature allows you to use Mailchimp's popup forms without any Drupal form configuration
- When creating campaigns, use the 'Preview content' button to verify entity tokens render correctly before saving
- Interest groups provide more granular subscriber preferences than tags - use groups for subscriber-facing choices and tags for internal organization
- The double opt-in setting helps maintain list quality and can improve deliverability by confirming valid email addresses
- Map entity fields to merge fields to enable personalization in Mailchimp campaigns using merge tags like *|FNAME|*
- For debugging Mailchimp Events, enable the mailchimp_events_example submodule to manually test event creation and retrieval
Technical Details
Admin Pages 9
/admin/config/services/mailchimp
Configure the global Mailchimp settings including authentication method, API timeout, Connected Sites, batch processing, and webhook configuration.
/admin/config/services/mailchimp/oauth
Configure and complete OAuth authentication with Mailchimp. This is the recommended authentication method.
/admin/config/services/mailchimp/lists
View and manage Mailchimp audiences synchronized with your Drupal site. Configure webhook settings for each audience.
/admin/config/services/mailchimp/list_cache_clear
Clear the cached audience data to refresh information from Mailchimp.
/admin/config/services/mailchimp/fields
View all Mailchimp Subscription fields configured across entity types in your Drupal site. Provides batch update functionality for merge variables.
/admin/config/services/mailchimp/signup
Create and manage anonymous signup forms for Mailchimp audiences. Forms can be displayed as blocks or standalone pages.
/admin/config/services/mailchimp/signup/add
Create a new Mailchimp signup form with configurable display mode, audience selection, merge fields, interest groups, and GDPR settings.
/admin/config/services/mailchimp/campaigns
Create, view, edit, send, and manage Mailchimp email campaigns directly from Drupal.
/admin/config/services/mailchimp/campaigns/add
Create a new Mailchimp campaign with audience selection, template configuration, and Drupal entity content import.
Permissions 4
Hooks 7
hook_mailchimp_subscribe_success
Performs an action upon successfully subscribing to an audience.
hook_mailchimp_unsubscribe_success
Performs an action upon successfully unsubscribing from an audience.
hook_mailchimp_process_webhook
Perform an action during the firing of a Mailchimp webhook. Called when Mailchimp sends webhook notifications for events like unsubscribes or profile updates.
hook_mailchimp_lists_mergevars_alter
Alter mergevars before they are sent to Mailchimp during subscription or update operations.
hook_mailchimp_lists_interest_groups_alter
Alter interest groups before they are sent to Mailchimp.
hook_mailchimp_campaign_alter
Alter campaign recipients and template before saving to Mailchimp.
hook_mailchimp_campaign_content_alter
Alter campaign template and filtered content before sending.
Troubleshooting 8
Clear the Drupal cache and reload the page. The module caches Mailchimp data to improve performance. You can also use the 'Refresh Audiences' button on the settings page or the 'Refresh current template' button on the campaign form.
Check if the campaign has already been sent. Sent campaigns cannot be edited in Mailchimp or Drupal.
Mailchimp webhooks require a publicly accessible URL. The Mailchimp system cannot reach local development environments. Use a tunneling service like ngrok to expose your local site for webhook testing.
Enable popups for your site in your browser. The OAuth authentication flow opens a new window for Mailchimp login. If blocked, you may see an incomplete authentication state.
If batch processing is enabled, subscription changes are queued for cron processing. Changes will appear after the next cron run. For immediate updates, disable batch processing in the settings or run cron manually.
Ensure you have created at least one audience in your Mailchimp account. Clear the audience cache using the 'Reset Mailchimp Audience Cache' page. Also verify that each Mailchimp audience can only be assigned to one subscription field - if an audience is already in use, it won't appear as an option for other fields.
Verify that entity fields are correctly mapped to Mailchimp merge fields in the subscription field settings. Multi-value fields only sync their first value. Required merge fields must be mapped to required or calculated entity fields.
Only custom HTML templates with properly defined editable content areas are fully supported. Drag-and-drop templates cannot be edited from Drupal. Create a custom HTML template in Mailchimp with mc:edit regions.
Security Notes 6
- The 'administer mailchimp' permission grants access to API credentials and should only be given to trusted administrators
- Webhook endpoints use a hash-based validation - keep your webhook hash secret and change it if compromised
- OAuth tokens are stored in Drupal's state system - ensure proper access controls to the database and state API
- API keys (if used) should never be exposed in logs or error messages - the module obscures them in the UI
- GDPR consent checkbox functionality helps with compliance but organizations should ensure their overall privacy practices meet requirements
- Connected Sites JavaScript runs on specified paths - be mindful of which pages include external scripts for security and performance