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

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

2. Create a key

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

3. Copy all of it

   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

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

2. Paste the 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

   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, 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

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

2. Set the 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

   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

   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

   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

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

1. Add the template

   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

   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

   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

Related guides

• Automations overview
• Create a checkout
• Plandalf with Mailchimp