---
description: "Connect Mailchimp to Plandalf with an API key, then add buyers to an audience, tag them, record events that start Customer Journeys, and remove tags on refund."
---
# Mailchimp setup

Connect your Mailchimp account so your Plandalf automations can act on your audience. When someone buys, a sequence can add them to an audience, tag them with what they bought, and record an event such as `started_trial` that a Customer Journey starts from. When they’re refunded, another sequence can remove the tag again. Someone subscribing to or unsubscribing from an audience can also start a Plandalf sequence.

## Before you start

-   A Mailchimp account, and a Mailchimp login that can open **Extras → API keys**.
-   The audience your buyers should join. Every step and trigger asks which audience to use.
-   The merge fields you plan to fill, set up in Mailchimp first. Unlike tags, Mailchimp doesn’t create a merge field the first time a value is sent for it.
-   A Plandalf checkout to connect it to, if you want purchases to reach Mailchimp.

## Get your Mailchimp API key

1.  [Open your API keys](#open-mailchimp-api-keys)

    Log in to Mailchimp. Open your profile menu, choose **Extras**, then **API keys**.

2.  [Create a key](#create-mailchimp-api-key)

    Click **Create A Key**, name it, for example “Plandalf”, and generate it.

3.  [Copy all of it](#copy-mailchimp-api-key)

    Copy the whole key, including the part after the dash, such as `-us21`. That part is the data centre your account lives in, and Plandalf needs it to reach your account. Mailchimp may only show the full key once, so copy it before you close the window.

The key works for every audience in the account. If you delete it in Mailchimp, the connection stops working and you will need to paste a new key into Plandalf.

## Connect Mailchimp to Plandalf

1.  [Find Mailchimp in the Marketplace](#find-mailchimp-in-marketplace)

    In Plandalf, open **Automation** in the sidebar and choose the **Marketplace** tab. Find **Mailchimp** under **Available now** and click **Connect**.

2.  [Paste the key](#paste-mailchimp-key)

    In the **Connect Mailchimp** window, keep or change the **Integration name**, paste your key into **API Key**, then click **Connect**.

3.  [Check the result](#check-mailchimp-connection)

    Plandalf checks the key with Mailchimp straight away by loading your account. When you see **Mailchimp connected**, choose **Build an automation** to start a sequence, or **Not now**.

Your connection now appears under **Automation → My apps**. You can connect more than one Mailchimp account; each step asks which account to use.

## Steps you can add

Every step below asks for:

-   **Audience** (required): the Mailchimp audience the contact belongs to, picked from your account.
-   **Email Address** (required): the contact’s email. In a purchase sequence, insert `{{trigger.customer_email}}` from the variable menu.

The steps that add something (a contact, a tag, an event) add the contact to the audience first if they aren’t in it yet, so you don’t need a separate create step. Those steps also have **Status for New Contacts**, which only applies to someone new to the audience:

-   **Subscribed** (the default): they get your marketing emails.
-   **Pending**: Mailchimp emails them to confirm first (double opt-in).
-   **Transactional**: they’re in the audience, but not on your marketing list.

Existing contacts keep their status, so a step never resubscribes someone who unsubscribed.

### Add or Update Contact

Adds a contact to the audience, or updates the one with that email.

-   **First Name**, usually `{{trigger.customer_first_name}}`.
-   **Last Name**, usually `{{trigger.customer_last_name}}`.
-   **Status for New Contacts**.
-   **Merge Fields**: pairs of a Mailchimp merge tag and a value, for example `PLAN` and `{{trigger.line_items_summary}}`. Use the tags shown in Mailchimp under **Audience → Settings → Audience fields and `*|MERGE|*` tags**. You can type a tag in lower case or with its `*|...|*` wrapper; Plandalf upper-cases it and strips the wrapper. Blank values are skipped, so an empty variable never wipes data in Mailchimp.
-   **Tags** (optional): pick tags, or type a name to create one.

### Add Tags to Contact

Adds one or more tags to a contact. Tags are added to the ones the contact already has.

-   **Tags** (required): pick tags from your Mailchimp audiences, or type a name to create the tag. Typed entries can use variables from the trigger or earlier steps.
-   **First Name**, used if the contact is new to the audience.
-   **Status for New Contacts**.

### Remove Tags from Contact

Removes one or more tags, for example when someone is refunded. If the email isn’t in the audience, the step is skipped rather than failed.

-   **Tags** (required): pick the tags to remove, or type the exact tag name.

### Record Event

Records a custom event on the contact. In Mailchimp, start a Customer Journey from an event with the same name to send the right emails after a purchase.

-   **Event Name** (required): the event as Mailchimp will show it, for example `started_trial`. Use 2 to 30 letters, numbers, dashes or underscores. Spaces become underscores, so “Started trial” is sent as `Started_trial`. Mailchimp matches the journey’s starting point on this exact name, so keep it the same in both places.
-   **Event Properties**: extra details for the event, as name and value pairs, for example `plan` and `{{trigger.line_items_summary}}`. Names are reduced to letters, numbers and underscores, values are sent as text, and blank values are skipped.
-   **Occurred At**: when it happened, for example `{{trigger.paid_at}}`. Leave it blank to use the time the step runs.
-   **First Name**, used if the contact is new to the audience.
-   **Status for New Contacts**.

> [!NOTE]
> **Purchases are sent as events, not Mailchimp orders**
> Record Event sends a purchase to Mailchimp as a custom event on the contact. Mailchimp events don’t carry revenue, and Plandalf doesn’t send orders to Mailchimp’s ecommerce API, so purchases don’t appear as Mailchimp orders or products. To keep what someone paid, add it as an event property or a merge field, and use tags to segment buyers.

### Unsubscribe Contact

Unsubscribes a contact from the audience’s marketing emails. They stay in the audience as unsubscribed. If the email isn’t in the audience, the step is skipped rather than failed.

## Start a sequence from Mailchimp

Choose **Mailchimp** as the trigger app to start a Plandalf sequence from something that happens in an audience:

-   **Contact Subscribed**: someone subscribes to the audience.
-   **Contact Unsubscribed**: someone unsubscribes from the audience.

Each trigger asks for the **Audience** to listen to. You don’t need to set up anything in Mailchimp. When you save the trigger, Plandalf adds a webhook to that audience, which you can see in Mailchimp under **Audience → Settings → Webhooks**, and the trigger’s **2\. Config** tab shows **Connected to Mailchimp**. Mailchimp checks the address before it accepts the webhook. Deleting the trigger removes the webhook again. Every delivery carries a secret key that Plandalf checks, so nobody else can start your sequence.

Each trigger gives later steps the contact’s `email`, `first_name`, `last_name`, `contact_id` and `merge_fields`, plus `audience_id`, `event_type` and `occurred_at`. Contact Unsubscribed also gives the `reason` and `unsubscribe_action` Mailchimp reports. A common use is the [Enroll in Promo step](https://plandalf.com/docs/product-guides/integrations/plandalf#steps-plandalf-can-run), which starts a promo timer for everyone who joins your list.

The triggers fire whoever made the change: the contact, someone on your Mailchimp account, or an app using the API. That includes Plandalf, so a sequence that adds buyers to an audience will also fire **Contact Subscribed** on that audience for each new subscriber.

## Example: tag app-trial buyers and start a Customer Journey

This sequence tags everyone who starts an app trial and records an event, so a Customer Journey can send the trial emails.

1.  [Create the sequence](#mailchimp-example-create)

    Go to **Automation → My Sequences**, create a sequence and name it, for example “App trials to Mailchimp”.

2.  [Set the trigger](#mailchimp-example-trigger)

    Choose **Plandalf** as the app and **Checkout Completed** as the trigger event. Under **Offer**, pick the trial checkout. On **3\. Test**, pick a recent checkout as the sample record so the variable menu fills with real values.

3.  [Tag the buyer](#mailchimp-example-tag)

    Click **Add a step**, choose **Mailchimp** and **Add Tags to Contact**, and pick your Mailchimp account. Pick the **Audience**, set **Email Address** to `{{trigger.customer_email}}`, add “App trial” to **Tags**, and set **First Name** to `{{trigger.customer_first_name}}`.

4.  [Record the event](#mailchimp-example-event)

    Add a second step: **Mailchimp**, **Record Event**. Use the same audience and email, set **Event Name** to `started_trial`, add an **Event Properties** pair of `plan` and `{{trigger.line_items_summary}}`, and set **Occurred At** to `{{trigger.paid_at}}`.

5.  [Start the Customer Journey](#mailchimp-example-journey)

    In Mailchimp, create a Customer Journey for the same audience, choose the **Event** starting point with the event name `started_trial`, and add your trial emails to it.

6.  [Test and turn it on](#mailchimp-example-test)

    Run each step’s test. Testing makes a real change in Mailchimp, so use your own email or a test contact. Then turn the sequence **On**.

Test purchases skip automations by default. To try the whole flow with a test card, open the sequence’s **Settings**, switch on **Run on test purchases**, buy through the checkout’s test link, and switch it off again when you’re done.

## Remove the tag on refund

Take the tag back from refunded buyers with the [Remove access on refund](https://plandalf.com/docs/product-guides/integrations/plandalf#remove-access-on-refund) template.

1.  [Add the template](#mailchimp-refund-add)

    Go to **Automation → Templates**, find **Remove access on refund** and click **\+ Add**. Pick the same checkout as your purchase sequence. Plandalf creates the sequence and opens it.

2.  [Pick the audience and tags](#mailchimp-refund-tags)

    Open the **Remove Tags from Contact** step. **Email Address** is already set to `{{trigger.customer_email}}`. Pick the **Audience** and the tags your purchase sequence adds, such as “App trial”.

3.  [Turn it on](#mailchimp-refund-on)

    The trigger is **Invoice Refunded** with **Full refunds only** on, so a partial refund leaves the tags alone. Turn the sequence **On**.

The template adds a removal step for every connected app that has one, so you may see steps for other apps in the same sequence. Set them up too, or delete the ones you don’t need.

## Common errors

| What you see | What to do |
| --- | --- |
| “That doesn’t look like a Mailchimp API key” when connecting | The key is missing the part after the dash, such as `-us21`. Copy the whole key from **Extras → API keys**, or create a new one. |
| **Authentication failed** when connecting | Mailchimp’s reason is shown with it. Check the key hasn’t been deleted in Mailchimp. Plandalf keeps the failed connection in **My apps**. Open it there, fix the key and choose **Test Connection**, rather than connecting again. |
| “Pick the Mailchimp audience in this step” | **Audience** is empty. Pick the audience the contact belongs to. |
| “Email is empty” | The email field didn’t resolve. Map it to `{{trigger.customer_email}}` or another step’s email output, and check the trigger sample has an email. |
| “… is not a valid email address” | The email field resolved to something that isn’t an email. Check which variable it uses. |
| “At least one tag is required” | **Tags** on **Add Tags to Contact** is empty, or every entry resolved to blank. Pick or type a tag. |
| “Pick the Mailchimp tags to remove” | **Tags** on **Remove Tags from Contact** is empty. Pick a tag. |
| “Event name is empty” | **Event Name** on **Record Event** is blank. Type the name your Customer Journey starts on. |
| “… can’t be a Mailchimp event name” | Use 2 to 30 letters, numbers, dashes or underscores, for example `started_trial`. |
| “… is not a date Mailchimp can read” | **Occurred At** isn’t a date. Use a date variable such as `{{trigger.paid_at}}`, or leave it blank. |
| A step fails with Mailchimp’s reason, such as “Your merge fields were invalid. PLAN: This merge field does not exist.” | Plandalf passes on what Mailchimp said. For merge fields, add the field to the audience in Mailchimp, or fix the tag in **Merge Fields**. |
| Remove Tags from Contact or Unsubscribe Contact shows **skipped** | The audience has no contact with that email. Nothing needed changing. |
| “Mailchimp didn’t accept the webhook” on a Mailchimp trigger | Mailchimp’s reason is shown underneath. Fix it, usually a deleted key or a removed connection, then click **Try again**. |
| A step fails with a rate limit message | Mailchimp allows 10 simultaneous connections per API key. Plandalf retries twice automatically. If it still fails, re-run the step once the burst has passed. |

## Related guides

-   [Automations overview](https://plandalf.com/docs/product-guides/integrations/plandalf)
-   [Create a checkout](https://plandalf.com/docs/product-guides/checkouts/create)
-   [Plandalf with Mailchimp](site:/platforms/mailchimp)

Source: https://plandalf.com/docs/product-guides/integrations/mailchimp