Mailchimp

This connector uses the Mailchimp Marketing API v3.0.

Datacenter-prefixed base URL (Mailchimp-specific quirk): each account lives on a numbered datacenter — us1, us2, … us21, etc. — and the API URL embeds it: https://us{N}.api.mailchimp.com/3.0. The datacenter suffix is the last segment of your API key after the dash (so an API key with -us6 at the end lives on us6). The adapter takes the datacenter as an env var MAILCHIMP_DC and substitutes it into the base URL — if you set the wrong DC you'll get 404 NotResolved errors.

Setup:

1. Sign in to Mailchimp → bottom-left avatar → Profile → Extras → API keys → Create a key.
2. The key Mailchimp issues you looks roughly like <32-hex-chars>-usN. Whatever the suffix says (-usN) IS your datacenter.
3. Set MAILCHIMP_API_KEY = the full key (including -usN); set MAILCHIMP_DC = usN (e.g. us6).

Authentication: Bearer token. The engine sends Authorization: Bearer ${MAILCHIMP_API_KEY}. Mailchimp also supports HTTP Basic with anystring:API_KEY but Bearer is cleaner and equally valid since 2019.

Audience IDs vs list IDs: Mailchimp renamed 'lists' to 'audiences' in the UI but the API still calls them lists. The list_id in URLs is a 10-character alphanumeric (e.g. a1b2c3d4e5) — find it via mailchimp_list_audiences once and pin it.

Member subscriber_hash: members are addressed by the MD5 hash of the lowercase email, NOT the raw email. Most tools that operate on a member accept either the raw email OR the hash and the adapter passes whatever you give it — but Mailchimp returns 404 if you pass the original-case email when the lowercase hash is expected. Always lowercase email before hashing if you compute it yourself.

PUT vs POST: Mailchimp uses PUT to upsert a member (creates if missing, updates if exists) — mailchimp_upsert_member does this. POST /members would error on duplicate. Stick with the adapter's upsert tool unless you specifically need to fail on duplicate.

Status values: when subscribing a member, status must be subscribed, unsubscribed, cleaned, pending (double opt-in) or transactional. Use subscribed for direct opt-in, pending if the list requires double opt-in.

Tags: tags on members are managed via a dedicated endpoint (/members/{hash}/tags) — mailchimp_update_member_tags accepts an array like [{name: 'vip', status: 'active'}, {name: 'cold', status: 'inactive'}]. Setting active adds the tag; inactive removes it.

Campaign workflow: campaigns have 3 phases — create (POST /campaigns), set content (PUT /campaigns/{id}/content — not exposed here, use the Mailchimp UI for templating), then send (POST /campaigns/{id}/actions/send). For pure trigger-on-existing-campaign, just call mailchimp_send_campaign with the campaign ID.

Rate limits: ~10 concurrent connections per user; daily caps scale with plan. On 429, back off.

Out of scope here: webhooks, marketing automation journeys, e-commerce store sync, transactional email (use the separate Mandrill / Mailchimp Transactional API for that), file manager, conversations.