Mailchimp Integration

What You Can Do

| Feature | Description |
|---------|-------------|
| OAuth Connection | One-click secure connection (no API keys needed) |
| Campaign Management | Create and send campaigns from ILLIXIS |
| Audience Sync | Access your Mailchimp lists automatically |
| Performance Tracking | Opens, clicks, bounces, unsubscribes |
| Webhook Events | Real-time tracking of email engagement |
| Sender Email | Configure verified sender address |

Connect Mailchimp

Step 1: Start Connection

1. Go to Settings → Integrations
2. Find Mailchimp section
3. Click Connect Mailchimp

You'll be redirected to Mailchimp to authorize access.

Step 2: Authorize ILLIXIS

On Mailchimp:

1. Log in to your account
2. Review permissions requested:

• Read lists and audiences
• Send campaigns
• Read campaign reports

3. Click Allow

You'll be redirected back to ILLIXIS with confirmation.

Step 3: Verify Connection

After connection:

• Green checkmark appears in Integrations
• Your Mailchimp account name displays
• Audience list count shows
• Connected date appears

What Gets Connected

Mailchimp Data Synced:

• All audience lists (name, ID, subscriber count)
• Campaign templates
• Account metadata
• Data center endpoint (us1, us2, etc.)

Access Token:

• Never expires (OAuth2 perpetual token)
• Stored encrypted in database
• Revocable from Mailchimp dashboard

Configure Sender Email

Mailchimp requires a verified sender email. Configure this separately:

1. Go to Settings → Branding
2. Find Mailchimp Sender Email field
3. Enter verified email (must match Mailchimp verified address)
4. Click Save

Fallback Logic (if not set):

• Uses tenant owner email
• Falls back to hello@{domain}
• Falls back to newsletter@{slug}.com

Why This Matters: Mailchimp rejects campaigns with unverified sender emails. Verify your address in Mailchimp first, then add it to ILLIXIS.

Send Campaigns

From Email Campaign Builder

1. Go to Marketing → Email Campaigns
2. Create or select campaign
3. Click Generate Campaign (or already generated)
4. Click Send button

Send Options:

| Option | Action |
|--------|--------|
| Send Now | Immediate delivery to Mailchimp list |
| Save Draft | Creates campaign in Mailchimp but doesn't send |

Select Audience

When sending:

1. List dropdown appears (auto-populated from Mailchimp)
2. Select target audience
3. Confirm send

List Details Include:

• List name
• Subscriber count
• Last updated

Campaign Creation Flow

Behind the scenes:

1. Create campaign - Mailchimp regular campaign created
2. Set content - HTML body uploaded
3. Send (if requested) - Campaign sent immediately
4. Record ID - Mailchimp campaign ID saved to ILLIXIS

Settings Applied:

• Subject line (from campaign or subject options)
• Preview text
• From name (tenant brand name)
• Reply-to (configured sender email)
• Inline CSS enabled

Track Performance

View Campaign Metrics

1. Go to Marketing → Email Campaigns
2. Find sent campaign
3. Click Refresh Metrics button

Metrics Tracked:

| Metric | Description |
|--------|-------------|
| Delivered | Successfully delivered emails |
| Opens | Total opens (includes repeats) |
| Unique Opens | Distinct recipients who opened |
| Open Rate | (Unique opens / Delivered) × 100 |
| Clicks | Total clicks on links |
| Unique Clicks | Distinct recipients who clicked |
| Click Rate | (Unique clicks / Delivered) × 100 |
| Click-to-Open Rate | (Unique clicks / Unique opens) × 100 |
| Bounces | Hard + soft bounces |
| Bounce Rate | (Bounces / Delivered) × 100 |
| Unsubscribes | Opt-outs after this campaign |
| Unsubscribe Rate | (Unsubscribes / Delivered) × 100 |
| Spam Complaints | Abuse reports |

Automatic Metric Refresh

Daily Refresh:

• All active campaigns refresh metrics automatically
• Scheduled task: refresh-campaign-metrics-daily
• Runs at 2:00 AM system time

Manual Refresh:

• Click Refresh Metrics button anytime
• Takes 2-5 seconds
• Updates stored metrics immediately

Webhook Events (Real-Time)

If webhooks are registered (automatic on connect):

• Opens tracked instantly
• Clicks recorded with URL
• Bounces logged
• Unsubscribes processed
• Spam complaints captured

Webhook URL: https://app.illixis.io/marketing-automation/webhooks/mailchimp/?secret={secret}

Webhook Registration

Automatic Registration

Webhooks register automatically when you connect Mailchimp:

• Registers on all audience lists
• Tracks: unsubscribes, bounces (cleaned)
• Ignores: subscribes, profile updates, campaign sends

Verify Webhooks

Check if webhooks are active:

1. Log in to Mailchimp dashboard
2. Go to Audience → Settings → Webhooks
3. Look for ILLIXIS webhook URL
4. Status should be "Active"

Events Tracked

| Event | Tracked | Purpose |
|-------|---------|---------|
| Unsubscribe | ✅ Yes | Add to suppression list |
| Cleaned (Bounce) | ✅ Yes | Add to suppression list |
| Subscribe | ❌ No | Not needed |
| Profile Update | ❌ No | Not needed |
| Campaign | ❌ No | Not needed |

Webhook Security

Webhooks are secured with a shared secret to verify that incoming requests are genuinely from Mailchimp. This is configured automatically when you connect your account.

Suppression List Sync

What Gets Suppressed

ILLIXIS fetches suppression data from Mailchimp:

• Unsubscribed members (reason: unsubscribe)
• Cleaned members (reason: bounce)

Sync Process

1. Fetches all lists for account
2. For each list:

• Queries unsubscribed members (status=unsubscribed)
• Queries cleaned members (status=cleaned)

3. Adds to your ILLIXIS suppression list
4. Future campaigns skip these addresses

When Sync Happens

Automatic:

• Daily suppression list refresh task
• After webhook events (real-time)

Manual:

• Contact support to trigger manual sync

Automation Schedule

ILLIXIS automatically syncs your Mailchimp data on a regular schedule to keep metrics and suppression lists current.

| Task | Schedule | What It Does |
|------|----------|--------------|
| Campaign Metrics Sync | Daily at 7:30 AM UTC | Updates opens, clicks, bounces, unsubscribes for all sent campaigns |
| Suppression List Sync | Daily at 4:00 AM UTC | Imports unsubscribes, bounces, and complaints from Mailchimp |
| Automation Performance | Every 6 hours | Refreshes metrics for Mailchimp automation workflows |
| Audience Counts | Daily | Updates subscriber counts for all connected lists |

Notes:

• All times are in UTC (Coordinated Universal Time)
• Manual refresh is available anytime via the Refresh Metrics button
• Webhooks provide real-time updates between scheduled syncs

Campaign Status Flow

| Status | Meaning |
|--------|---------|
| draft | Campaign exists in Mailchimp but not sent |
| sent | Successfully sent to Mailchimp list |
| error | Send failed (see error message) |

Error Handling

Common Errors:

| Error | Cause | Fix |
|-------|-------|-----|
| Invalid token | OAuth expired or revoked | Reconnect Mailchimp |
| List not found | List ID doesn't exist | Select different list |
| Sender email unverified | Email not verified in Mailchimp | Verify in Mailchimp dashboard |
| API endpoint error | Wrong data center | Reconnect to refresh metadata |

Error Details:

• Error messages are displayed in the campaign list view
• Details include the Mailchimp API response

Disconnect Mailchimp

How to Disconnect

1. Go to Settings → Integrations
2. Find Mailchimp section
3. Click Disconnect
4. Confirm action

What Happens

Removed:

• OAuth access token (deleted from database)
• Cached audience lists

Preserved:

• Historical campaign data
• Metrics already fetched
• Campaign IDs (for reference)

Impact:

• Can't send new campaigns via Mailchimp
• Can't refresh metrics for Mailchimp campaigns
• Existing campaigns remain visible in ILLIXIS

Multi-Platform Support

Automatic Platform Detection

ILLIXIS supports 3 email platforms:

1. Klaviyo (API key)
2. Mailchimp (OAuth)
3. Resend (API key)

Default Platform: Set in Settings → Integrations → Default Email Platform

Campaign-Specific Platform

When creating campaigns:

• Defaults to tenant's default platform
• Can override per campaign
• ILLIXIS routes to correct service automatically

Troubleshooting

Connection Issues

Problem: "Invalid OAuth session" error Fix:

1. Clear browser cache
2. Try connecting again
3. Ensure cookies enabled

Problem: "Mailchimp connection failed" Fix:

1. Check Mailchimp service status
2. Try different browser
3. Contact support if persists

Campaign Send Issues

Problem: Campaign stuck in "draft" status Cause: Campaign was saved as draft instead of sent immediately Fix: Go to Mailchimp dashboard and send manually

Problem: "Sender email unverified" error Fix:

1. Log in to Mailchimp
2. Go to Settings → Verified Domains
3. Verify sender email
4. Update in ILLIXIS Settings → Branding

Problem: Campaign creates but doesn't send Check:

1. Mailchimp list still exists?
2. Sender email verified?
3. Campaign content valid HTML?
4. Check the campaign detail page for error messages

Metrics Not Updating

Problem: Metrics show zero despite opens/clicks Fix:

1. Click Refresh Metrics button
2. Wait 24 hours for Mailchimp to process data
3. Check webhook registration in Mailchimp dashboard

Problem: Webhooks not working Check:

1. Webhook URL registered in Mailchimp?
2. Webhook status "Active" in Mailchimp?
3. Contact support if webhooks appear active but events are not being received

Best Practices

Before Sending

1. Verify sender email in Mailchimp first
2. Test with small list before full audience
3. Preview content in Email Campaign Builder
4. Check audience size before confirming send

After Sending

1. Wait 24 hours for metrics to stabilize
2. Refresh metrics manually if needed
3. Check bounce rate (>5% indicates list quality issues)
4. Review unsubscribes (high rate = content/frequency problem)

List Hygiene

1. Remove bounced addresses - Mailchimp auto-cleans
2. Honor unsubscribes - Automatic via webhooks
3. Monitor spam complaints - High rate hurts deliverability
4. Re-engagement campaigns - Target inactive subscribers

Compliance

CAN-SPAM:

• Mailchimp includes unsubscribe link automatically
• Physical address required (set in Mailchimp)
• Honor opt-outs within 10 business days

GDPR:

• Only send to subscribers who opted in
• Provide clear unsubscribe mechanism
• Mailchimp handles consent tracking

FAQ

Q: Does Mailchimp access token expire? A: No. Mailchimp OAuth tokens never expire unless manually revoked.

Q: Can I use multiple Mailchimp accounts? A: No. One Mailchimp connection per tenant. Disconnect and reconnect to switch accounts.

Q: What happens to campaigns if I disconnect? A: Historical data preserved. New campaigns can't be sent until reconnected.

Q: Can I edit campaigns after sending? A: No. Mailchimp campaigns are immutable after send. Create a new campaign instead.

Q: Why do metrics take 24 hours to update? A: Mailchimp processes campaign data in batches. Opens/clicks within first hour may not appear immediately.

Q: Can I send to segments instead of full lists? A: Not currently supported. Send to full list only. Use Mailchimp dashboard for segment targeting.

Q: What's the difference between total opens and unique opens? A: Total opens counts every open (one person can open 5 times = 5 opens). Unique opens counts distinct recipients (one person = one open).

Q: Can I schedule campaigns for future send? A: Not via ILLIXIS. Send as draft to Mailchimp, then schedule in Mailchimp dashboard.

Q: Why does sender email field exist separately from Mailchimp settings? A: Mailchimp requires verified addresses. ILLIXIS stores your preferred verified address to auto-populate campaigns.

Related Features

• Email Campaign Builder - Create campaigns
• Klaviyo Integration - Alternative ESP
• Email Analytics - Cross-platform metrics
• Campaign Planner - Multi-channel coordination

Last Updated: February 5, 2026 Version: 1.0 Integration Type: OAuth 2.0