> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Mailchimp

> Sync your email list subscribers between Hiveku and Mailchimp

When someone signs up on your Hiveku site, you want them in Mailchimp a second later. This guide gets newsletter signups flowing straight into your Mailchimp audience with tags, merge fields, and optional double opt-in.

<CardGroup cols={2}>
  <Card title="Via Zapier" icon="plug">
    Zero-code, 5 minutes. Good for low-to-medium volume.
  </Card>

  <Card title="Via Mailchimp API" icon="code">
    Direct API integration. More control over tags and fields.
  </Card>
</CardGroup>

## Step 1: Get Your Mailchimp API Credentials

<Steps>
  <Step title="Log in to Mailchimp">
    Go to [mailchimp.com](https://mailchimp.com) and sign in.
  </Step>

  <Step title="Create an API key">
    Navigate to **Account > Extras > API keys**. Click **Create a key**. Copy the key — it looks like `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-us20`.
  </Step>

  <Step title="Note your data center">
    The suffix after the dash is your data center. In `xxxx-us20`, the DC is `us20`. You'll need it for the API URL.
  </Step>

  <Step title="Find your Audience ID">
    Go to **Audience > All contacts > Settings > Audience name and defaults**. The Audience ID is near the bottom — looks like `a1b2c3d4e5`.
  </Step>
</Steps>

## Step 2: Store Credentials in Hiveku

Add three environment variables:

* `MAILCHIMP_API_KEY` — the full key including the `-us20` suffix
* `MAILCHIMP_AUDIENCE_ID` — your audience ID
* `MAILCHIMP_DC` — just the data center (e.g., `us20`)

See [Environment Variables](/how-tos/env-vars).

## Step 3: Create a Subscribe Workflow

<Steps>
  <Step title="Create the workflow">
    Go to **Workflows > New Workflow**. Name it `Newsletter → Mailchimp`.
  </Step>

  <Step title="Add a webhook trigger">
    Wire this URL to your newsletter signup form.
  </Step>

  <Step title="Add an HTTP Request action">
    ```
    POST https://{{env.MAILCHIMP_DC}}.api.mailchimp.com/3.0/lists/{{env.MAILCHIMP_AUDIENCE_ID}}/members
    Headers:
      Authorization: Bearer {{env.MAILCHIMP_API_KEY}}
      Content-Type: application/json
    Body:
    {
      "email_address": "{{trigger.email}}",
      "status": "subscribed",
      "merge_fields": {
        "FNAME": "{{trigger.name}}"
      },
      "tags": ["website-signup"]
    }
    ```
  </Step>
</Steps>

## Double Opt-In

Double opt-in is the safest pattern for deliverability and required in many jurisdictions (Germany, Canada).

Change `"status": "subscribed"` to `"status": "pending"`. Mailchimp will send its own confirmation email, and the subscriber only moves to `subscribed` after they click the link.

<Tip>
  Double opt-in typically drops your signup rate by 10-20% but delivers far more engaged subscribers. For most newsletters the tradeoff is worth it.
</Tip>

## Tags for Segmentation

Tags let you segment later. Use them liberally:

```json theme={null}
"tags": ["website-signup", "blog-reader", "2026-q2"]
```

Common patterns:

* **Source**: `website-signup`, `webinar-attendee`, `conference-2026`
* **Content interest**: `ai-topics`, `design-topics`
* **Stage**: `lead`, `customer`, `churned`

Mailchimp lets you build segments from any tag combination in the UI.

## Merge Fields

Mailchimp's default merge fields are `FNAME`, `LNAME`, `EMAIL`. Custom ones you create appear with whatever tag you set (e.g., `COMPANY`, `ROLE`).

```json theme={null}
"merge_fields": {
  "FNAME": "{{trigger.first_name}}",
  "LNAME": "{{trigger.last_name}}",
  "COMPANY": "{{trigger.company}}"
}
```

Find the exact merge tag names in Mailchimp under **Audience > Settings > Audience fields and *|MERGE|* tags**.

## Unsubscribe Sync

When users unsubscribe in Mailchimp, you probably want to update your own CRM.

<Steps>
  <Step title="Configure a Mailchimp webhook">
    In Mailchimp, go to **Audience > Settings > Webhooks**. Create a webhook pointing to a Hiveku workflow webhook URL.
  </Step>

  <Step title="Subscribe to unsubscribe events">
    Check the **Unsubscribes** event.
  </Step>

  <Step title="Handle the event in Hiveku">
    The webhook delivers a payload with the email. Update your CRM: `UPDATE contacts SET marketing_opt_in = false WHERE email = '{{trigger.data.email}}'`.
  </Step>
</Steps>

<Warning>
  Always respect consent. If a visitor didn't explicitly opt in (pre-checked boxes don't count), don't add them to marketing lists. GDPR and CAN-SPAM penalties are serious — a single complaint can have cascading consequences.
</Warning>

## Avoiding Sync Loops

When Mailchimp sends you an unsubscribe webhook, don't let your sync workflow push the change back to Mailchimp. Flag events that originated from Mailchimp and skip those writes:

```
IF {{trigger.source}} == 'mailchimp' THEN skip sync to Mailchimp
```

## Alternative: Use Zapier

If you'd rather not touch the API, Zapier has a Mailchimp integration out of the box. See [Connect Zapier](/how-tos/connect-zapier). Trigger: form submission. Action: "Add subscriber to list." Five minutes, no code.

## Verify It Worked

1. Submit your newsletter form with a test email
2. Check **Workflows > Runs** — the HTTP call should return 200
3. In Mailchimp, go to **Audience** and search for the email — the subscriber should appear with the correct tags and merge fields

## Troubleshooting

<AccordionGroup>
  <Accordion title="404 Not Found">
    The data center in the URL is wrong. Your API key ends with `-us20` (or similar) — that part goes into the URL as `us20.api.mailchimp.com`. If the key ends in `-us1`, use `us1.api.mailchimp.com`. A mismatched DC always returns 404.
  </Accordion>

  <Accordion title="'Member Exists' error">
    Expected if the email is already in the audience. Mailchimp treats this as a 400 response with `title: "Member Exists"`. Handle it gracefully — treat it as a successful subscribe (it is, from your perspective). Log it and move on.
  </Accordion>

  <Accordion title="Merge fields aren't populating">
    You're using the wrong tag names. Mailchimp uses all-caps merge tags: `FNAME` not `first_name`, `LNAME` not `last_name`. Check **Audience > Settings > Audience fields** for the exact tags, including any custom ones you've added.
  </Accordion>

  <Accordion title="Unsubscribe loops">
    User unsubscribes in Mailchimp → Mailchimp webhook fires → Hiveku workflow updates your CRM → your CRM sync pushes back to Mailchimp → Mailchimp re-unsubscribes them → webhook fires again. Add a source flag to skip the reverse sync when the event came from Mailchimp.
  </Accordion>

  <Accordion title="403 Forbidden">
    The API key is valid but doesn't have access to the audience. Either the key was generated under a different Mailchimp account, or your Mailchimp user role doesn't have list access. Check the account dropdown in Mailchimp — you might be logged into the wrong one.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Newsletter Signup Form" icon="envelope-open" href="/how-tos/add-newsletter-signup">
    Add the form to your site if you haven't yet
  </Card>

  <Card title="Email Suppressions" icon="ban" href="/how-tos/email-suppressions">
    Keep your list clean across tools
  </Card>
</CardGroup>