# Mailchimp

Add, update and tag audience members, create, schedule and send campaigns, manage templates, and read campaign reports in Mailchimp.

## Connect Mailchimp

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `mailchimp` and choose **Mailchimp**.
3. Choose **Sign in with Mailchimp**.
4. Press **Sign in with Mailchimp** at the bottom of the sheet, then choose your account in Mailchimp’s window and allow access.

Or choose **Paste your API key**, paste it, and press **Test and save**. It stays until someone deletes it.

Sign in with Mailchimp, or paste an API key (Mailchimp › Profile › Extras › API keys › Create A Key). A key works for the whole account it belongs to.

**What if it says “Sign-in isn’t set up here yet”?**

Signing in with Mailchimp needs a Mailchimp app on this installation, and it has none yet. Until it is set up, **Paste your API key** works without it.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Mailchimp sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Mailchimp’s developer settings ([Mailchimp’s guide](https://mailchimp.com/developer/marketing/guides/quick-start/#generate-your-api-key)).
2. In GoRunner, copy the **Redirect address to add in Mailchimp’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Mailchimp app?**

Yes. In the sheet, open **Use your own Mailchimp app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Mailchimp**. The trigger uses the same connection as the steps.

### On Audience Event

Fires when one of the chosen events happens on the audience. Publishing the workflow creates the audience's webhook in Mailchimp; unpublishing removes it. Mailchimp signs a webhook only when it is set up as signed, so the check is a random secret in this webhook's own address (?gr_secret=…), which only Mailchimp is given: a delivery without it is refused. When Mailchimp returns a signing secret for the webhook, its signature (X-Mailchimp-Signature) is required too; a signed retry is accepted for up to 24 hours, and a repeat of one already run starts nothing. Mailchimp retries a delivery it could not hand over for 75 minutes; a retry of the same event starts no second run. The webhook is checked daily and made again if Mailchimp dropped it.

- **Audience · Required**: The audience to watch.
- **Events · Required**: Which events start the workflow. Options: Subscribed, Unsubscribed, Profile updated, Email address changed, Address cleaned (bounced), Campaign sent or cancelled, Subscribed to SMS (beta), Unsubscribed from SMS (beta), SMS phone number changed (beta), SMS campaign sent (beta).
- **Made By · Optional**: Whose actions count: the subscriber's own, someone's in Mailchimp, or another app's through the API. Empty counts all three. Options: The subscriber (forms, links), Someone in Mailchimp, The API (other apps, integrations).

A later step can use its data, such as `{{trigger.data}}`, `{{trigger.fired_at}}`, `{{trigger.type}}`. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Mailchimp

Add a **Mailchimp** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Member](https://docs.gorunner.io/apps/mailchimp#fields-f-member): Create · Create or Update · Get · Get Many · Search · Update · Add Note · Archive · Delete Permanently
- [Member Tag](https://docs.gorunner.io/apps/mailchimp#fields-f-membertag): Add · Remove · Get Many
- [Campaign](https://docs.gorunner.io/apps/mailchimp#fields-f-campaign): Create · Get · Get Many · Update Settings · Set Content · Get Content · Send Test Email · Send · Schedule · Unschedule · Replicate · Resend to Non-Openers · Delete
- [Audience](https://docs.gorunner.io/apps/mailchimp#fields-f-audience): Create · Get · Get Many · Delete
- [Interest Group](https://docs.gorunner.io/apps/mailchimp#fields-f-listgroup): Get Many · Get Categories
- [Template](https://docs.gorunner.io/apps/mailchimp#fields-f-template): Create · Get · Get Many · Update · Delete
- [Report](https://docs.gorunner.io/apps/mailchimp#fields-f-report): Get · Get Many · Get Email Activity · Get Click Details

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Mailchimp can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Mailchimp says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Mailchimp is `pieceId: "mailchimp"` with `actionId: "mailchimp"`, set by `resource` and an `operation_…` field, such as `operation_audience`. Its trigger is `mailchimptrigger` / `mailchimp_event`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Mailchimp › Member

### Create

- **Audience · Required**: The audience the member is in.
- **Email · Required**: The member's email address. For Get, Update, Add Note, Archive and Delete, the member's id (the MD5 hash of the lowercase address) works too.
- **Status · Required**: The member's subscription status. For Create or Update, the status a NEW member gets. Options: Subscribed, Unsubscribed, Cleaned, Pending (sends a confirmation email), Transactional. Default: Subscribed.
- **Merge Fields · Optional**: The audience fields by merge tag, such as {"FNAME": "Sam", "LNAME": "Lee"}. Address fields take an object: {"ADDRESS": {"addr1": "…", "city": "…", "state": "…", "zip": "…"}}.
- **Interest Groups · Optional**: Groups the member is in, by interest id, such as {"9143cf3bd1": true, "3a2a927344": false}. Interest Group › Get Many lists the ids.
- **Tags · Optional**: Tags for a new member, separated by commas (Member Tag › Add changes them later).
- **Language · Optional**: The member's language code, such as en, de, fr.
- **VIP · Optional**: Mark the member as a VIP. Off by default.
- **Email Type · Optional**: The kind of email the member prefers. Empty leaves the audience's default. Options: HTML, Plain text.
- **Signup IP · Optional**: The IP address the member signed up from.
- **Signup Time · Optional**: When the member signed up (ISO 8601, such as 2026-11-01T09:00:00+00:00).
- **Skip Merge Field Validation · Optional**: Accept the member even when a required merge field is missing. Off by default.

### Create or Update

- **Audience · Required**: The audience the member is in.
- **Email · Required**: The member's email address. For Get, Update, Add Note, Archive and Delete, the member's id (the MD5 hash of the lowercase address) works too.
- **Status · Required**: The member's subscription status. For Create or Update, the status a NEW member gets. Options: Subscribed, Unsubscribed, Cleaned, Pending (sends a confirmation email), Transactional. Default: Subscribed.
- **Set Status · Optional**: Change the status of the member as well (for Create or Update: also of a member who is already on the audience). Empty leaves it as it is. Options: Subscribed, Unsubscribed, Cleaned, Pending (sends a confirmation email), Transactional.
- **Merge Fields · Optional**: The audience fields by merge tag, such as {"FNAME": "Sam", "LNAME": "Lee"}. Address fields take an object: {"ADDRESS": {"addr1": "…", "city": "…", "state": "…", "zip": "…"}}.
- **Interest Groups · Optional**: Groups the member is in, by interest id, such as {"9143cf3bd1": true, "3a2a927344": false}. Interest Group › Get Many lists the ids.
- **Tags · Optional**: Tags for a new member, separated by commas (Member Tag › Add changes them later).
- **Language · Optional**: The member's language code, such as en, de, fr.
- **VIP · Optional**: Mark the member as a VIP. Off by default.
- **Email Type · Optional**: The kind of email the member prefers. Empty leaves the audience's default. Options: HTML, Plain text.
- **Signup IP · Optional**: The IP address the member signed up from.
- **Signup Time · Optional**: When the member signed up (ISO 8601, such as 2026-11-01T09:00:00+00:00).
- **Skip Merge Field Validation · Optional**: Accept the member even when a required merge field is missing. Off by default.

### Get, Archive and Delete Permanently

- **Audience · Required**: The audience the member is in.
- **Email · Required**: The member's email address. For Get, Update, Add Note, Archive and Delete, the member's id (the MD5 hash of the lowercase address) works too.

### Get Many

- **Audience · Required**: The audience the member is in.
- **Status · Optional**: Only members with this status. Empty lists every member. Options: Subscribed, Unsubscribed, Cleaned, Pending, Transactional, Archived.
- **Changed After · Optional**: Only members changed after this time (ISO 8601).
- **Changed Before · Optional**: Only members changed before this time (ISO 8601).
- **Opted In After · Optional**: Only members who opted in after this time (ISO 8601).
- **Return All · Optional**: Read every member, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many members to return (1–5000). Default: 50. Shows when **Return All** is off.

### Search

- **Search Text · Required**: An email address, or part of a name or address. A full address finds that member exactly.
- **Audience · Optional**: Search one audience only. Empty searches every audience.

### Update

- **Audience · Required**: The audience the member is in.
- **Email · Required**: The member's email address. For Get, Update, Add Note, Archive and Delete, the member's id (the MD5 hash of the lowercase address) works too.
- **Set Status · Optional**: Change the status of the member as well (for Create or Update: also of a member who is already on the audience). Empty leaves it as it is. Options: Subscribed, Unsubscribed, Cleaned, Pending (sends a confirmation email), Transactional.
- **New Email · Optional**: A new email address for the member. Empty keeps the current one.
- **Merge Fields · Optional**: The audience fields by merge tag, such as {"FNAME": "Sam", "LNAME": "Lee"}. Address fields take an object: {"ADDRESS": {"addr1": "…", "city": "…", "state": "…", "zip": "…"}}.
- **Interest Groups · Optional**: Groups the member is in, by interest id, such as {"9143cf3bd1": true, "3a2a927344": false}. Interest Group › Get Many lists the ids.
- **Language · Optional**: The member's language code, such as en, de, fr.
- **VIP · Optional**: Mark the member as a VIP. Off by default.
- **Email Type · Optional**: The kind of email the member prefers. Empty leaves the audience's default. Options: HTML, Plain text.
- **Skip Merge Field Validation · Optional**: Accept the member even when a required merge field is missing. Off by default.

### Add Note

- **Audience · Required**: The audience the member is in.
- **Email · Required**: The member's email address. For Get, Update, Add Note, Archive and Delete, the member's id (the MD5 hash of the lowercase address) works too.
- **Note · Required**: The note's text (at most 1,000 characters).

### Mailchimp › Member Tag

### Add and Remove

- **Audience · Required**: The audience the member is in.
- **Email · Required**: The member's email address, or their id (the MD5 hash of the lowercase address).
- **Tags · Required**: Tag names, separated by commas. A tag that does not exist yet is created.
- **Skip Automations · Optional**: Do not start the automations these tags would start. Off by default.

### Get Many

- **Audience · Required**: The audience the member is in.
- **Email · Required**: The member's email address, or their id (the MD5 hash of the lowercase address).
- **Return All · Optional**: Read every tag, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many tags to return (1–5000). Default: 50. Shows when **Return All** is off.

### Mailchimp › Campaign

### Create

- **Type · Required**: An HTML email, or a plain-text one. Options: Regular (HTML), Plain text. Default: Regular (HTML).
- **Audience · Required**: The audience the campaign goes to.
- **Segment or Tag ID · Optional**: Send to one saved segment or tag of the audience only (its numeric id). Empty sends to the whole audience.
- **Subject · Optional**: The email's subject line (at most 150 characters).
- **Preview Text · Optional**: The text shown after the subject in the inbox.
- **Title · Optional**: The campaign's name in Mailchimp (people never see it).
- **From Name · Optional**: The sender's name.
- **Reply To · Optional**: The reply-to address; Mailchimp needs it (a verified domain) before the campaign can be sent.
- **To Name · Optional**: How recipients are addressed, such as *|FNAME|*.
- **Content · Optional**: What goes into the campaign: your HTML, plain text, a saved template, or nothing yet (Set Content adds it later). Options: HTML, Plain text, A saved template, None yet. Default: HTML.
- **HTML · Optional**: The email's HTML (Content: HTML; for Set Content, HTML or Plain Text). Mailchimp merge tags (*|FNAME|*) work.
- **Template · Required**: A saved template the campaign starts from. Shows when **Content** is **A saved template**.
- **Plain Text · Optional**: The email's text (Content: Plain text). For an HTML email, its plain-text version; Mailchimp makes one when empty.

### Get, Get Content, Send, Unschedule, Replicate, Resend to Non-Openers and Delete

- **Campaign · Required**: The campaign.

### Get Many

- **Status · Optional**: Only campaigns in this state. Empty lists every campaign. Options: Draft, Paused, Scheduled, Sending, Sent.
- **Audience · Optional**: Only campaigns to this audience.
- **Created After · Optional**: Only campaigns created after this time (ISO 8601).
- **Sent After · Optional**: Only campaigns sent after this time (ISO 8601).
- **Sort By · Optional**: The order of the list. Options: Created, newest first, Sent, newest first. Default: Created, newest first.
- **Return All · Optional**: Read every campaign, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many campaigns to return (1–5000). Default: 50. Shows when **Return All** is off.

### Update Settings

- **Campaign · Required**: The campaign.
- **Subject · Optional**: The email's subject line (at most 150 characters).
- **Preview Text · Optional**: The text shown after the subject in the inbox.
- **Title · Optional**: The campaign's name in Mailchimp (people never see it).
- **From Name · Optional**: The sender's name.
- **Reply To · Optional**: The reply-to address; Mailchimp needs it (a verified domain) before the campaign can be sent.
- **To Name · Optional**: How recipients are addressed, such as *|FNAME|*.

### Set Content

- **Campaign · Required**: The campaign.
- **HTML · Optional**: The email's HTML (Content: HTML; for Set Content, HTML or Plain Text). Mailchimp merge tags (*|FNAME|*) work.
- **Plain Text · Optional**: The email's text (Content: Plain text). For an HTML email, its plain-text version; Mailchimp makes one when empty.

### Send Test Email

- **Campaign · Required**: The campaign.
- **Test Addresses · Required**: Where the test goes, separated by commas.
- **Send As · Optional**: The HTML or the plain-text version. Options: HTML, Plain text. Default: HTML.

### Schedule

- **Campaign · Required**: The campaign.
- **Send At · Required**: When to send, in UTC (ISO 8601). Mailchimp schedules on the quarter hour: :00, :15, :30 or :45.

### Mailchimp › Audience

### Create

- **Name · Required**: The audience's name.
- **Permission Reminder · Required**: Why people get these emails, such as You signed up for news on our website.
- **Default From Name · Required**: The sender's name campaigns to this audience start with.
- **Default From Email · Required**: The sender's address campaigns start with.
- **Default Subject · Optional**: The subject campaigns start with.
- **Language · Optional**: The audience's language code, such as en.
- **Company · Required**: The company or organisation in the footer of every email (anti-spam law).
- **Address · Required**: The street address in the footer.
- **Address Line 2 · Optional**
- **City · Required**
- **State or Region · Optional**
- **Postal Code · Optional**
- **Country · Required**: A two-letter country code, such as US, DE.
- **Let Members Pick HTML or Text · Optional**: Members choose the format of the emails they get. Off by default.
- **Double Opt-in · Optional**: People who sign up through Mailchimp's forms confirm by email first. Off by default.

### Get and Delete

- **Audience · Required**: The audience.

### Get Many

- **Return All · Optional**: Read every audience, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many audiences to return (1–5000). Default: 50. Shows when **Return All** is off.

### Mailchimp › Interest Group

### Get Many

- **Audience · Required**: The audience.
- **Group Category · Required**: The category whose groups to list (Get Categories lists them).
- **Return All · Optional**: Read every group, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many groups to return (1–5000). Default: 50. Shows when **Return All** is off.

### Get Categories

- **Audience · Required**: The audience.
- **Return All · Optional**: Read every group, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many groups to return (1–5000). Default: 50. Shows when **Return All** is off.

### Mailchimp › Template

### Create

- **Name · Optional**: The template's name (at most 50 characters).
- **HTML · Optional**: The template's HTML; Mailchimp's template language (mc:edit) works.
- **Folder ID · Optional**: The template folder to put it in.

### Get and Delete

- **Template · Required**: The template.

### Get Many

- **Type · Optional**: Your own templates, Mailchimp's basic layouts or its themes. Empty lists all of them. Options: Saved templates, Basic layouts, Themes.
- **Return All · Optional**: Read every template, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many templates to return (1–5000). Default: 50. Shows when **Return All** is off.

### Update

- **Template · Required**: The template.
- **Name · Optional**: The template's name (at most 50 characters).
- **HTML · Optional**: The template's HTML; Mailchimp's template language (mc:edit) works.
- **Folder ID · Optional**: The template folder to put it in.

### Mailchimp › Report

### Get

- **Campaign · Required**: The campaign.

### Get Many

- **Sent After · Optional**: Only campaigns sent after this time (ISO 8601).
- **Return All · Optional**: Read every record, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many records to return (1–5000). Default: 50. Shows when **Return All** is off.

### Get Email Activity and Get Click Details

- **Campaign · Required**: The campaign.
- **Return All · Optional**: Read every record, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many records to return (1–5000). Default: 50. Shows when **Return All** is off.

Source: https://docs.gorunner.io/apps/mailchimp