How Mailchimp Integration Works

Source: mailchimp_controller.rb

• OAuth uses country-specific client IDs; the access token returned includes a data center suffix that determines which Mailchimp API server to use
• Batch sync excludes customers whose preferred_contact_method is set to "none"
• Subscriber upsert uses PUT with the MD5 hash of the lowercase email address as the key, preventing duplicate entries for the same email
• ALL subscribers pushed to Mailchimp are set to "subscribed" status — this WILL re-subscribe contacts who previously unsubscribed, creating a potential compliance risk under anti-spam laws (CAN-SPAM, GDPR)
• Batch sync failures are logged but not retried automatically

Support scenarios

• "Customers who unsubscribed from Mailchimp are getting emails again" → The sync sets ALL contacts to "subscribed" status, overriding their previous unsubscribe. This is a known compliance risk. The workshop should be warned that this may violate anti-spam regulations. Consider disabling the sync or filtering contacts before pushing.
• "Some customers aren't appearing in Mailchimp" → Customers with preferred_contact_method set to "none" are excluded from the batch sync. Check the customer's contact preferences in Workshop.
• "Mailchimp sync failed and contacts are missing" → Batch failures are logged but not retried. Check the logs for the specific error, fix the issue, and manually re-trigger the sync.
• "Mailchimp auth is failing" → OAuth uses country-specific client IDs. Verify the correct client ID is being used for the workshop's country. Also check that the access token's data center suffix matches the Mailchimp account's actual data center.