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

# Mailchimp

> Add or update LinkedIn contacts in a Mailchimp audience with merge fields and a tag that starts a Customer Journey.

> [!NOTE]
>
> **Pro plan.** Mailchimp works through a connection and HTTP steps, which are part of Pro and Agency (and the free trial). Anything you already have keeps working on every plan. See [Plans and billing](/help/account/billing.md).

When a contact with an email is ready for your newsletter, one **Webhook / HTTP** step adds or updates them in your Mailchimp audience, and a second adds a tag. A Customer Journey that starts on that tag takes it from there.

> [!NOTE]
>
> **How it connects:** Mailchimp's Marketing API with your API key. See Mailchimp's [Add or update list member](https://mailchimp.com/developer/marketing/api/lists/members/upsert-member) and [Add or remove member tags](https://mailchimp.com/developer/marketing/api/list-member-tags/) docs. The requests and answers below follow Mailchimp's docs.

## Before you start

* **Mailchimp plan:** the Marketing API is on every plan, including free; Customer Journeys and audience size depend on the plan.
* **An API key:** in Mailchimp, open **Profile > Extras > API keys** and create one. The part after the dash (for example `us21`) is your data center.
* **The audience id:** in **Audience > Settings > Audience name and defaults**.

## 1. Connect Mailchimp

In Kerux, open **Integrations > Connections**, click **Connect** on **Custom API** (under **Developers**):

* **How it signs in:** **Username and password**: any username (for example `kerux`), and the API key as password.
* **Base URL:** `https://us21.api.mailchimp.com/3.0` (use your own data center).

Click **Save**, then **Test connection**.

## 2. Add or update the member

Add a **Webhook / HTTP** step named `mailchimp`. Mailchimp's docs say the member endpoints take the email address in place of the MD5 hash:

```json theme={null}
{
  "method": "PUT",
  "url": "/lists/YOUR_AUDIENCE_ID/members/{{email}}",
  "bodyType": "json",
  "body": {
    "email_address": "{{email}}",
    "status_if_new": "pending",
    "merge_fields": { "FNAME": "{{contact.first_name}}", "LNAME": "{{contact.last_name | optional}}" }
  }
}
```

`pending` sends Mailchimp's confirmation email (double opt-in); use `subscribed` only if the person already agreed. Mailchimp answers with the member (trimmed):

```json theme={null}
{ "id": "f4b3c...", "email_address": "daniel@northwind.com", "status": "pending" }
```

## 3. Add the tag

A second **Webhook / HTTP** step:

```json theme={null}
{
  "method": "POST",
  "url": "/lists/YOUR_AUDIENCE_ID/members/{{email}}/tags",
  "bodyType": "json",
  "body": { "tags": [{ "name": "linkedin", "status": "active" }] }
}
```

Mailchimp answers `204` with no body. In Mailchimp, start your Customer Journey with "Tag added: linkedin".

## Test with one contact

In the **Builder**, click **Test** to open **Test on one contact** with your own email. Check the member, the tag and the confirmation email.

## Common errors

> [accordion] 401 API Key Invalid
>
> The key is wrong, or the data center in the **Base URL** doesn't match the key's suffix.

> [accordion] 400 Member In Compliance State
>
> The person unsubscribed or was cleaned before. Mailchimp won't re-add them through the API, by design.

> [accordion] 404 Resource Not Found
>
> The audience id is wrong. Copy it again from the audience's settings.

Related: [Webhook steps](/help/integrations/webhook-steps.md), [Brevo](/help/integration-guides/brevo.md), [Typeform](/help/integrations/forms/typeform.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.