Skip to main content
PRO Only
Pro Feature

This feature is only available in the Pro edition. Upgrade to Pro to access MailChimp integration.

Pro: MailChimp Integration

MailChimp Integration automatically adds users to your MailChimp email list when they download free products. Build your email list effortlessly while providing valuable content to your audience.

Overview​

The MailChimp integration:

  • Subscribes users to your MailChimp list after download
  • Applies dynamic tags based on downloaded products
  • Updates existing subscribers with new tags
  • Supports double opt-in for compliance
  • Handles errors gracefully with admin notifications

How It Works​

Subscription Flow​

When a user downloads with newsletter subscription:

  1. User completes email capture form
  2. Checks newsletter subscription box (or auto-subscribed)
  3. Download is processed
  4. User is added to MailChimp list
  5. Tags are applied to subscriber
  6. Confirmation email sent (if double opt-in enabled)

For Existing Subscribers​

If user is already subscribed:

  • Subscription status is maintained
  • New tags are added to existing tags
  • Contact information is updated
  • No duplicate subscriptions created

Prerequisites​

MailChimp Account​

You need:

  • Active MailChimp account
  • At least one audience (list)
  • API key with read/write permissions

Get API Key:

  1. Log in to MailChimp
  2. Go to Account > Extras > API Keys
  3. Click Create A Key
  4. Copy the API key

Email Capture Enabled​

MailChimp integration requires email capture:

  1. Go to Pro Edition > Tracking
  2. Enable "Enable email capture"
  3. Configure subscription option
  4. Save settings

See Email Capture for details.

Configuration​

Settings Location​

Go to WP Enhanced > Free Download Woo, then click Newsletter in the sidebar

API Key​

  1. Enter your MailChimp API key
  2. Click "Validate API Key"
  3. Wait for validation confirmation
  4. Save settings

List Selection​

  1. After API key is validated
  2. Select your MailChimp audience from dropdown
  3. Click "Validate List ID"
  4. Wait for validation confirmation
  5. Save settings

Double Opt-In​

Enable double opt-in:

  • Users receive confirmation email
  • Must click link to confirm subscription
  • GDPR compliant
  • Reduces spam subscriptions

Disable double opt-in:

  • Users subscribed immediately
  • No confirmation required
  • Faster list building
  • May include invalid emails

Recommendation: Enable for compliance and list quality.

Tags​

Add tags to subscribers for segmentation:

Static Tags:

free-download, lead, interested

Dynamic Tags with Placeholders:

product-{product_id}, {product_name}, downloaded-{variation_name}

Available Placeholders:

  • {product_id} - Product ID number
  • {product_name} - Product name
  • {variation_id} - Variation ID (if applicable)
  • {variation_name} - Variation name (if applicable)

Example:

free-download, product-{product_id}, {product_name}

Becomes:

free-download, product-123, Premium eBook

Subscription Options​

Email Capture Settings​

Configure how subscription is presented:

Optional Checkbox:

  • User chooses to subscribe
  • Checkbox not pre-checked
  • GDPR compliant

Text Only:

  • Informational text
  • No checkbox
  • No subscription

Hidden (Auto-Subscribe):

  • All users subscribed automatically
  • No checkbox shown
  • Ensure compliance

Required Checkbox:

  • User must check to download
  • Enforces subscription
  • May reduce conversions

Configure in Pro Edition > Tracking > Newsletter Subscription.

Subscription Text​

Customize the subscription checkbox label:

Subscribe to our newsletter for updates and exclusive content

Make it clear what users are subscribing to.

Dynamic Tagging​

Product-Based Tags​

Tag subscribers by downloaded product:

Configuration:

Tags: product-{product_id}, {product_name}

Result for Product ID 123 "SEO Guide":

product-123, SEO Guide

Variation-Based Tags​

Tag by product variation:

Configuration:

Tags: {product_name}, {variation_name}

Result for "T-Shirt" variation "Large Blue":

T-Shirt, Large Blue

Use Cases​

Content Segmentation:

Tags: ebook-{product_name}, content-download

Lead Scoring:

Tags: lead-{product_id}, interest-{product_name}

Campaign Tracking:

Tags: campaign-summer-2024, {product_name}

Managing Subscribers​

In MailChimp​

View and manage subscribers:

  1. Log in to MailChimp
  2. Go to Audience > All contacts
  3. Search by email or tag
  4. View subscriber details
  5. Edit or remove as needed

Subscriber Data​

Data synced to MailChimp:

  • Email address
  • First name
  • Last name
  • Tags
  • Subscription date
  • Source (WordPress site)

Unsubscribes​

Users can unsubscribe via:

  • MailChimp unsubscribe link in emails
  • Your website (if you add unsubscribe form)
  • Directly in MailChimp

Unsubscribes are respected - users won't be re-subscribed on future downloads.

Error Handling​

Validation Errors​

If API key or list ID is invalid:

  • Error message displayed in settings
  • Subscription disabled until fixed
  • Admin notification sent

Subscription Errors​

If subscription fails:

  • Download still proceeds
  • Error logged to debug log
  • Admin notification sent (optional)
  • User not informed (to avoid confusion)

Admin Notifications​

Configure email notifications for errors:

add_filter('somdn_mailchimp_notify_on_error', '__return_true');

add_filter('somdn_mailchimp_error_email', function($email) {
    return 'admin@example.com';
});

Troubleshooting​

API Key Not Validating​

If API key validation fails:

  1. ✅ Verify key is copied correctly (no spaces)
  2. ✅ Check key hasn't been deleted in MailChimp
  3. ✅ Ensure key has proper permissions
  4. ✅ Try generating new key
  5. ✅ Check server can connect to MailChimp API

List ID Not Validating​

If list validation fails:

  1. ✅ Verify API key is validated first
  2. ✅ Check list exists in MailChimp
  3. ✅ Ensure list is active (not deleted)
  4. ✅ Try different list
  5. ✅ Check for API rate limits

Users Not Being Subscribed​

If subscriptions aren't working:

  1. ✅ Verify email capture is enabled
  2. ✅ Check subscription option is configured
  3. ✅ Ensure API key and list are validated
  4. ✅ Look for errors in debug log
  5. ✅ Test with your own email

Tags Not Applying​

If tags aren't added:

  1. ✅ Verify tags are configured in settings
  2. ✅ Check placeholder syntax is correct
  3. ✅ Ensure product/variation data exists
  4. ✅ Look for errors in debug log
  5. ✅ Check tags in MailChimp

Double Opt-In Not Working​

If confirmation emails aren't sent:

  1. ✅ Verify double opt-in is enabled
  2. ✅ Check MailChimp email settings
  3. ✅ Look in spam folder
  4. ✅ Test with different email address
  5. ✅ Check MailChimp sending reputation

Developer Hooks​

Filters​

somdn_newsletter_sub_tags Modify tags before subscription.

add_filter('somdn_newsletter_sub_tags', function($tags, $product_id, $variation_id) {
    // Add custom tag
    $tags[] = 'custom-tag';
    
    // Add user role tag
    $user = wp_get_current_user();
    if ($user->ID) {
        $tags[] = 'role-' . $user->roles[0];
    }
    
    return $tags;
}, 10, 3);

somdn_mailchimp_subscriber_data Modify subscriber data before sending.

add_filter('somdn_mailchimp_subscriber_data', function($data, $email) {
    // Add custom merge fields
    $data['merge_fields']['CUSTOM'] = 'value';
    
    return $data;
}, 10, 2);

somdn_mailchimp_notify_on_error Enable error notifications.

add_filter('somdn_mailchimp_notify_on_error', '__return_true');

Actions​

somdn_mailchimp_subscribed Fires after successful subscription.

add_action('somdn_mailchimp_subscribed', function($email, $list_id, $tags) {
    // Log subscription
    error_log("Subscribed: {$email} to list {$list_id}");
}, 10, 3);

somdn_mailchimp_error Fires on subscription error.

add_action('somdn_mailchimp_error', function($error, $email) {
    // Custom error handling
    error_log("MailChimp error for {$email}: {$error}");
}, 10, 2);

Use Cases​

Lead Magnets​

Offer free downloads as lead magnets:

  • Create valuable content (eBooks, guides, templates)
  • Require email to download
  • Auto-subscribe to newsletter
  • Nurture leads with email campaigns

Content Upgrades​

Provide bonus content:

  • Blog post with free download
  • Readers subscribe to access
  • Tag by content topic
  • Send related content

Product Launches​

Build launch lists:

  • Offer preview content
  • Collect interested subscribers
  • Tag by product interest
  • Notify on launch

Segmentation​

Segment audience by interest:

  • Tag by downloaded product
  • Create targeted campaigns
  • Personalize email content
  • Improve engagement

Best Practices​

List Building​

  • Quality over quantity: Focus on engaged subscribers
  • Clear value: Explain newsletter benefits
  • Opt-in: Use optional or required checkbox
  • Welcome email: Send welcome series

Tagging Strategy​

  • Consistent naming: Use clear tag names
  • Hierarchical tags: product-category-name
  • Limit tags: Don't over-tag subscribers
  • Document tags: Keep tag list documented

Compliance​

  • Privacy policy: Mention email collection
  • Unsubscribe: Include in all emails
  • Double opt-in: Enable for compliance
  • Data protection: Secure subscriber data

Email Marketing​

  • Regular emails: Maintain consistent schedule
  • Valuable content: Provide useful information
  • Segmentation: Use tags for targeting
  • A/B testing: Test subject lines and content

Integration with Other Services​

Alternative Email Services​

While this plugin integrates with MailChimp, you can use webhooks or custom code to integrate with:

  • ConvertKit
  • ActiveCampaign
  • Drip
  • AWeber
  • GetResponse

Contact support for integration assistance.

Zapier Integration​

Connect to 1000+ apps via Zapier:

  1. Use MailChimp's Zapier integration
  2. Trigger on new subscriber
  3. Filter by tag
  4. Connect to other apps

CRM Integration​

Sync subscribers to CRM:

  • Use MailChimp's CRM integrations
  • Or custom API integration
  • Sync contact data
  • Track lead source