Add every WhatsApp opt-in directly to your Mailchimp audience, look up subscriber status before sending a campaign, and keep your email and WhatsApp contact lists in sync automatically, without anyone touching a CSV.
Before following this guide, read the External API Request step foundation guide. It covers every field in the step interface so this guide can stay focused on Mailchimp-specific values.
Every Mailchimp account has a unique data centre prefix such as us1, us6, or us21. The base URL for ALL API calls is https://YOUR_DC.api.mailchimp.com/3.0/. The prefix is the last part of your API key after the final hyphen. Key ending in -us6 means your base URL is https://us6.api.mailchimp.com/3.0/. Wrong prefix returns a WrongDatacenter error even with a valid key.
Mailchimp Basic Auth ignores the username entirely. You can put any non-empty string there. Mailchimp's own docs use the word 'anystring'. Only the API key (the password part after the colon) is validated. Base64-encode anystring:YOUR_API_KEY.
-us6,
your DC is us6
and your base URL is
https://us6.api.mailchimp.com/3.0/.anystring:YOUR_API_KEY
and prepend Basic .API key example: a1b2c3d4e5f6789abc01234567890abc-us6
↑ everything before the last hyphen
Data centre: us6
Base URL: https://us6.api.mailchimp.com/3.0/
Auth string to Base64-encode: anystring:a1b2c3d4e5f6789abc01234567890abc-us6
Base64 result: YW55c3RyaW5nOmExYjJjM2Q0...
Authorization header: Basic YW55c3RyaW5nOmExYjJjM2Q0...Mailchimp Marketing API v3: mailchimp.com/developer
Every Mailchimp audience has a unique List ID. You need it for all member-level endpoints. Fetch it once and store it.
{{
"lists": [
{{
"id": "abc123def4",
"name": "Main Audience",
"stats": {{"member_count": 4821}}
}}
]
}}
Copy: lists[0].id = "abc123def4"
This is your list_id for all subsequent calls.When a customer opts in to WhatsApp messaging, add them to your Mailchimp audience in the same automation. The PUT endpoint is an upsert: it creates the subscriber if they are new, or updates their record if they already exist.
{{
"email_address": "{{{{customer_email}}}}",
"status_if_new": "subscribed",
"status": "subscribed",
"merge_fields": {{
"FNAME": "{{{{customer_name}}}}",
"PHONE": "{{{{customer_phone}}}}"
}},
"tags": ["whatsapp-optin"]
}}
Response:
{{
"id": "8bdbf060209f35b52087992a3cbdf4d",
"email_address": "priya@example.com",
"status": "subscribed",
"merge_fields": {{"FNAME": "Priya"}}
}}
status_if_new: used only when creating (not updating).
status: used for both create and update.
"tags" adds tags but does NOT remove existing ones.The URL requires MD5(lowercase(email)). For priya@example.com: MD5('priya@example.com') = 8bdbf060209f35b52087992a3cbdf4d. In WA.Expert's External API Request step, you can hardcode a known subscriber's hash for testing, or use a helper step. For dynamic lookups, the search-members endpoint below is simpler; it accepts a plain email query.
To check whether a WhatsApp contact is already subscribed to your Mailchimp list before deciding what to send them, use the search endpoint. No hash needed.
{{
"exact_matches": {{
"members": [
{{
"id": "8bdbf060209f35b52087992a3cbdf4d",
"email_address": "priya@example.com",
"status": "subscribed",
"merge_fields": {{"FNAME": "Priya", "PHONE": "+919820000001"}},
"tags": [{{"name": "whatsapp-optin"}}],
"stats": {{"avg_open_rate": 0.42, "avg_click_rate": 0.12}}
}}
],
"total_items": 1
}},
"full_search": {{"members": [], "total_items": 0}}
}}
Map: exact_matches.members[0].email_address
exact_matches.members[0].status
exact_matches.total_items (0 = not subscribed)Map these response paths to WhatsApp variables:
| Variable name | Response path | Example value |
|---|---|---|
| sub_status | exact_matches.members[0].status | subscribed |
| sub_name | exact_matches.members[0].merge_fields.FNAME | Priya |
| sub_found | exact_matches.total_items | 1 |
| sub_open_rate | exact_matches.members[0].stats.avg_open_rate | 0.42 |
sub_found = 0 means not subscribed. Branch your flow: if sub_found > 0, they are already on your list; if 0, add them with the PUT step.
| Status | Meaning | Use in PUT body |
|---|---|---|
| subscribed | Active, receives campaigns | status: subscribed |
| unsubscribed | Opted out; cannot be re-subscribed via API | status: unsubscribed |
| cleaned | Hard bounce; email is invalid | Not settable via API |
| pending | Awaiting double opt-in confirmation | status_if_new: pending |
| transactional | Non-marketing contact | status: transactional |
Set status_if_new: pending if you want Mailchimp to send a confirmation email before the contact becomes subscribed.
Trigger: Customer messages 'SUBSCRIBE' on WhatsApp.
Bot asks: 'Please share your email address to join our mailing list.'
Customer: priya@example.com
Stored as {{customer_email}}, {{customer_name}} = Priya Sharma.
Step 1 — Search (check if already subscribed):
GET https://us6.api.mailchimp.com/3.0/search-members
?query=priya@example.com&list_id=abc123def4
Authorization: Basic ...
Response: exact_matches.total_items = 0 (not yet subscribed)
Conditions: if total_items > 0 -> 'You are already subscribed. Thank you!'
if total_items = 0 -> run Step 2
Step 2 — Add subscriber (PUT upsert):
PUT https://us6.api.mailchimp.com/3.0/lists/abc123def4/members/8bdbf060...
Body: {{email_address: 'priya@example.com', status_if_new: 'subscribed',
status: 'subscribed', merge_fields: {{FNAME: 'Priya'}},
tags: ['whatsapp-optin']}}
Response: {{status: 'subscribed', id: '8bdbf060...'}}
Bot replies: 'You are now subscribed to our mailing list, Priya!
You will receive email updates at priya@example.com.'| Symptom | Likely cause | Fix |
|---|---|---|
| WrongDatacenter error | Base URL uses the wrong DC prefix | Check the end of your API key. Key ending -us6 means base URL must be https://us6.api.mailchimp.com/3.0/. Fix the DC prefix in the URL. |
| 401 Unauthorized | API key invalid or incorrectly formatted in Base64 | Recompute Base64(anystring:YOUR_API_KEY). Ensure the full key including the -us6 suffix is included as the password. |
| 404 on member endpoint | Wrong list_id or subscriber not in that list | Confirm the list_id from GET /lists. The subscriber must exist in that specific list. |
| 400 on PUT: cannot re-subscribe | Member status is unsubscribed | Mailchimp does not allow re-subscribing an unsubscribed member via API. The member must re-subscribe themselves via a form. |
| exact_matches.total_items = 0 | Email not in this list | The contact is not subscribed to the list_id you queried. They may be in a different audience, or may not be subscribed at all. |
| tags not appearing | Tag names are case-sensitive | Ensure tag names match exactly what exists in your Mailchimp account. Tags are created automatically on first use but the name must be consistent. |
Brevo Marketing API: API key auth, contact sync and transactional email triggers.
Read guide →Klaviyo API: Bearer token, profile lookup and list subscription.
Read guide →Free trial, no credit card. If you get stuck, we answer live on WhatsApp.