Mailchimp API — SKILL.md

---
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 (Klaviyo, Brevo, ConvertKit)."
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["mailchimp", "email", "marketing", "api", "automation", "saas"]
---

# 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.