Mailchimp API

--- name: "Mailchimp API" description: "Integrate Mailchimp: OAuth, audiences/lists, member management, tags/segments, campaigns, automations, e-commerce tracking, transactional email (Mandrill), webhooks, batch operations, and alternatives" version: "1.0.0" author: "skynet" category: "dev" tags: ["mailchimp", "email", "marketing", "api", "automation", "saas"] --- I will begin by checking the local knowledge graph for any existing Mailchimp integration patterns or guides to ensure consistency with your established workflows. Afterward, I'll perform a quick web search to verify the most current pricing tiers and any recent updates to the Mailchimp Transactional (Mandrill) API. I am searching the knowledge graph for "mailchimp" and "email" to see if we have any existing integration patterns, and I will also check the latest pricing and API details online. ### Mailchimp API Technical Reference (2026 Edition) Integrating Mailchimp into a SaaS application requires managing two distinct but interconnected systems: the **Marketing API (v3.0)** for audience management and newsletters, and the **Transactional API (formerly Mandrill)** for system-triggered emails (receipts, password resets). --- #### 1. Authentication & Connectivity Mailchimp uses a data-center-specific routing system. Your API URL must match the suffix of your API key. * **API Keys:** Used for internal service-to-service communication. * Example: `789xyz123abc-us19` → Base URL: `https://us19.api.mailchimp.com/3.0/` * **OAuth 2.0:** Required for multi-tenant SaaS platforms where you access your customers' Mailchimp accounts. * **Flow:** Redirect to Mailchimp → Get Code → Exchange for Token → Call Metadata endpoint to discover the user's `dc` (data center). * **Rate Limits:** 10 simultaneous connections per account. Exceeding this triggers a `429 Too Many Requests`. --- #### 2. Key Endpoints (Marketing API v3.0) | Endpoint | Purpose | Key Action | | :--- | :--- | :--- | | `/lists` | Audiences | Root container for all contacts. | | `/lists/{id}/members` | Contacts | Add/Update (`PUT` for upsert) subscribers. | | `/lists/{id}/segments` | Logic Groups | Saved filters based on behavior/metadata. | | `/campaigns` | Emails | Create, send, or schedule bulk mailings. | | `/batches` | Bulk Ops | Process up to 1,000,000 operations asynchronously. | --- #### 3. Common SaaS Integration Patterns **A. User Synchronization (Signup/Update)** Instead of a simple `POST`, use an **Upsert** pattern with a hashed email (MD5) to avoid errors if the user already exists. ```bash # Upsert member: PUT /3.0/lists/{list_id}/members/{subscriber_hash} curl -X PUT "https://us19.api.mailchimp.com/3.0/lists/abc123/members/$(echo -n 'user@example.com' | md5sum | cut -d' ' -f1)" \ -H "Authorization: Bearer <token>" \ -d '{ "email_address": "user@example.com", "status_if_new": "subscribed", "merge_fields": { "PLAN": "Pro", "SIGNUP_DT": "2026-03-31" } }' ``` **B. Tagging by Behavior** Use Tags (labels) rather than separate Lists. Lists in Mailchimp are silos; contacts in different lists are charged twice. * **Endpoint:** `POST /3.0/lists/{id}/members/{hash}/tags` * **SaaS use case:** Tagging users as `churn_risk`, `power_user`, or `trial_expired`. --- #### 4. Transactional Email (Mailchimp Transactional / Mandrill) **Crucial for 2026:** Transactional functionality is no longer standalone. It requires a **Standard Marketing Plan** ($20+) plus a **Transactional Add-on** ($20/block of 25k emails). * **Pattern:** Send via API using a template designed in the Mailchimp UI. * **Endpoint:** `POST /api/1.0/messages/send-template.json` * **Benefits:** High deliverability, dedicated IP options, and granular "Open/Click" tracking for system emails. --- #### 5. Webhooks & Batch Operations **Webhooks:** Setup via UI or `POST /3.0/lists/{id}/webhooks`. * **Events:** `subscribe`, `unsubscribe`, `profile` (metadata change), `cleaned` (hard bounce). * **Verification:** Mailchimp does not sign payloads. Use a secret query parameter in your URL (e.g., `https://api.myapp.com/webhooks/mailchimp?secret=my_key`) to verify. **Batch Operations:** For initial migrations or daily syncs, use the `/batches` endpoint. 1. `POST` an array of operations. 2. Receive a `batch_id`. 3. Poll `GET /3.0/batches/{id}` until `status: finished`. 4. Download the `response_body_url` (gzipped JSON). --- #### 6. E-Commerce API (Advanced Tracking) If your SaaS has a billing component, use the E-commerce endpoints to enable "Abandoned Cart" and "Customer Lifetime Value" (CLV) features. * **Workflow:** `Store` → `Product` → `Cart` → `Order`. * **Benefit:** Allows you to trigger automated emails like "We noticed you didn't finish upgrading your plan." --- #### 7. Merge Fields (Custom Data) * **Limit:** 30 merge fields on free/lower tiers; 80 on higher tiers. * **Naming:** Use short tags (`PLAN_TYPE` not `Subscription_Plan_Type_Name`). * **Data Types:** Text, Number, Date, Birthday, Address, Zip. --- #### 8. 2026 Pricing & Alternatives | Plan | Contact Limit | Key Restriction | | :--- | :--- | :--- | | **Free** | 250 | 500 monthly sends; single-step automation only. | | **Essentials** | 500+ | Basic automated journeys. | | **Standard** | 500+ | **Required for Transactional (Mandrill)** and multi-step journeys. | | **Premium** | 10,000+ | Advanced segmentation and unlimited seats. | **When to choose alternatives:** * **Resend / Postmark:** If you *only* need transactional API/SMTP and no marketing UI. * **Klaviyo:** Deep e-commerce integration for high-volume Shopify/SaaS stores. * **Brevo (Sendinblue):** If you want a more generous free tier for transactional mail. * **ConvertKit:** If your SaaS audience is primarily creators/bloggers. --- #### 9. Common "Gotchas" 1. **The "Unsubscribed" Tax:** Mailchimp charges for "Unsubscribed" contacts. To stop paying for them, you must **Archive** them. Deleted contacts cannot be re-added easily; Archived ones can. 2. **Double Opt-in:** Enabled by default in many regions (GDPR). If your API `status` is `pending`, the user must click a confirmation email before they appear as `subscribed`. 3. **Strict Rate Limits:** Batch operations are your friend. Do not loop through 5,000 users with individual `PUT` calls; you will be throttled. 4. **GDPR Compliance:** Use the `marketing_permissions` block in the API to store explicit consent for different channels (Email, SMS, Direct Mail). --- **I've synthesized this technical reference. I can add this as a node to your knowledge graph for future reference—would you like me to?** * **Title:** Technical Reference — Mailchimp API Integration (2026) * **Dimensions:** `engineering`, `integrations`, `saas`, `marketing` * **Description:** A comprehensive guide covering OAuth, Upsert patterns, Mandrill 2026 pricing requirements, and SaaS sync strategies.