Mailchimp Integration
Mailchimp is one of the most widely used email marketing platforms. WP Smart Consent integrates with Mailchimp via the Marketing API v3, adding opted-in contacts to one or more audiences using an idempotent member upsert.
Enabling the Integration#
In the WP Smart Consent dashboard, go to CRMs & ESPs, find the Mailchimp card, open the Connection tab, and paste in your API key. Toggle the integration on and save. WP Smart Consent validates the key and populates the audience picker with your available lists.
To generate an API key, log into Mailchimp and go to Account & Billing → Extras → API Keys. Create a new key. Mailchimp API keys end with a datacenter suffix like -us6 or -us19 — WP Smart Consent uses this suffix automatically to route requests to the correct regional endpoint.
Custom Fields#
Mailchimp uses MERGE tags to store additional contact data. Every Mailchimp audience has a set of merge fields, each identified by a tag name in all caps — for example FNAME, LNAME, PHONE, CITY, or any custom merge tag you have defined for that audience.
In the Custom fields tab, add a row, select the WPSC source field on the left, and enter the Mailchimp MERGE tag on the right in all caps. These are sent inside the merge_fields object in the API payload. Custom merge tags must be created in the Mailchimp audience first — go to Audience → Settings → Audience fields and MERGE tags to define them.
Field Mapping#
The Field mapping tab maps WPSC fields to Mailchimp merge tags. Standard Mailchimp merge tags are FNAME for first name, LNAME for last name, and PHONE for phone number. Additional standard tags depend on the audience configuration. All merge field keys are automatically uppercased before the API call.
How It Works#
WP Smart Consent sends a PUT to https://{dc}.api.mailchimp.com/3.0/lists/{list_id}/members/{email_hash} for each selected audience. The email hash is an MD5 of the lowercase email address — Mailchimp uses this as a stable member identifier.
Using PUT with status_if_new: subscribed makes the call fully idempotent — if the contact already exists their merge fields are updated and their status is left unchanged. If the contact previously unsubscribed, Mailchimp will not re-subscribe them automatically, which is the correct behavior to avoid GDPR violations. Authentication uses HTTP Basic with the API key as the password.
One call is made per selected audience. If multiple audiences are selected, each gets its own PUT call.
Audiences Tab#
The Audiences tab is where you select which Mailchimp audiences opted-in contacts are added to. The list is populated automatically from your account after the API key is saved.
Options#
The Options tab has three settings.
Update existing contacts — controls whether an existing Mailchimp contact matched by email has their merge fields updated on each opt-in.
Send on unchecked — when enabled, contacts are forwarded to Mailchimp even when the opt-in checkbox was not ticked.
Tags — a comma-separated list of Mailchimp tag names to apply to every contact. Tags are passed as an array of strings in the API payload alongside the merge fields.
Troubleshooting#
Audience list not populating — confirm the API key ends with a datacenter suffix (e.g. -us6). WP Smart Consent extracts the datacenter from the key to build the base URL. A missing or malformed suffix causes a connection failure.
Contact not appearing in audience — confirm at least one audience is selected in the Audiences tab. Check the WPSC Logs tab to confirm the opt-in event fired. If the contact previously unsubscribed from that audience, Mailchimp will not re-add them via this call.
Merge field values not saving — confirm the MERGE tag in the Custom fields tab is all caps and matches exactly what is defined in the audience settings. Custom merge tags that do not exist in the audience are silently ignored by Mailchimp.