> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/marketing/mailchimp.md).

# Mailchimp

Connect Mailchimp to Google Sheets, BigQuery, or Excel — sync contacts, campaign reports, automations, and audience insights via Coupler.io.

Mailchimp is an email marketing platform that lets you manage audiences, send campaigns, and track performance. Connecting Mailchimp to Coupler.io lets you export your contacts, campaign reports, automations, and audience insights into the tools you already use — automatically and without code.

## Why connect Mailchimp to Coupler.io?

* **Centralize your email data** — pull contacts, campaign reports, and audience growth into Google Sheets, BigQuery, Excel, or Looker Studio in one place
* **Automate reporting** — schedule regular exports so your dashboards always reflect the latest campaign performance
* **Combine with other sources** — use Append or Join transformations to merge Mailchimp data with CRM, ad, or website analytics data
* **Send data to AI tools** — route campaign performance data to ChatGPT, Claude, Gemini, Perplexity, or Cursor for AI-driven analysis

## Prerequisites

* An active Mailchimp account (any plan)
* Admin or Manager-level access to the Mailchimp account you want to connect — read-only access may cause permission errors
* A Coupler.io account

## Quick start

{% hint style="success" %}
If you want campaign performance data, start with the **Campaigns report** entity — it gives you open rates, click rates, and delivery stats in one place without needing to join multiple entities.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow.** In Coupler.io, click **Add data flow**, then search for and select **Mailchimp** as your source.
{% endstep %}

{% step %}
**Authorize your Mailchimp account.** Click **Connect** and sign in to Mailchimp via the OAuth popup. Coupler.io will request read access to your account data. Once authorized, your account will appear in the source settings.
{% endstep %}

{% step %}
**Select an entity.** Choose the data entity you want to export — for example, **Campaigns report**, **Audience (list of contacts)**, or **Audience growth history**. If you select an audience-level entity, also pick the specific audience from the dropdown.
{% endstep %}

{% step %}
**Choose your destination.** Select where you want the data sent — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT or Claude — and configure the destination settings.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute a manual run. Once it completes successfully, your data will appear in the destination.
{% endstep %}
{% endstepper %}

## Mailchimp data overview

Coupler.io gives you access to ten Mailchimp entities covering your contacts, audiences, campaigns, and automations. Here's a breakdown of what's available in each.

## Entities at a glance

| Entity                       | Grain                      | Key use                                   |
| ---------------------------- | -------------------------- | ----------------------------------------- |
| Audience (list of contacts)  | One row per contact        | Segmentation, suppression lists, CRM sync |
| Audience activity            | One row per activity event | Contact-level engagement tracking         |
| Audience clients             | One row per email client   | Deliverability and rendering insights     |
| Audience growth history      | One row per month          | Subscriber trend reporting                |
| Audience interest categories | One row per interest group | Audience segmentation analysis            |
| Audience locations           | One row per location       | Geographic reporting                      |
| Automations                  | One row per automation     | Automation inventory and status           |
| List of audiences            | One row per audience       | Multi-audience account overview           |
| Campaigns                    | One row per campaign       | Campaign metadata and status              |
| Campaigns report             | One row per campaign       | Aggregated performance metrics            |

## Campaigns report

#### Performance metrics

| Field             | Description                            |
| ----------------- | -------------------------------------- |
| emails\_sent      | Total number of emails sent            |
| open\_rate        | Percentage of recipients who opened    |
| click\_rate       | Percentage of recipients who clicked   |
| unique\_opens     | Unique open count                      |
| unique\_clicks    | Unique click count                     |
| bounce\_rate      | Percentage of emails that bounced      |
| unsubscribe\_rate | Unsubscribes as a share of emails sent |
| soft\_bounces     | Soft bounce count                      |
| hard\_bounces     | Hard bounce count                      |
| abuse\_reports    | Spam complaint count                   |

#### Campaign metadata

| Field           | Description                              |
| --------------- | ---------------------------------------- |
| campaign\_id    | Unique campaign identifier               |
| campaign\_title | Internal campaign name                   |
| subject\_line   | Email subject line                       |
| send\_time      | Date and time the campaign was sent      |
| type            | Campaign type (regular, automated, etc.) |
| status          | Campaign status (sent, draft, etc.)      |
| list\_id        | ID of the audience it was sent to        |

## Audience (list of contacts)

#### Contact fields

| Field          | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| email\_address | Contact's email address                                          |
| status         | Subscription status (subscribed, unsubscribed, cleaned, pending) |
| first\_name    | First name                                                       |
| last\_name     | Last name                                                        |
| tags           | Tags applied to the contact                                      |
| member\_rating | Mailchimp's engagement score (1–5)                               |
| timestamp\_opt | Date the contact opted in                                        |
| ip\_opt        | IP address at opt-in                                             |
| language       | Preferred language                                               |
| vip            | Whether the contact is flagged as VIP                            |
| email\_client  | Email client used                                                |

## Audience growth history

#### Growth fields

| Field        | Description                     |
| ------------ | ------------------------------- |
| month        | Calendar month                  |
| existing     | Existing subscriber count       |
| imports      | Contacts added via import       |
| optins       | Organic opt-ins                 |
| unsubscribes | Unsubscribe count for the month |
| cleaned      | Emails cleaned (hard bounces)   |

## Automations

| Field               | Description                         |
| ------------------- | ----------------------------------- |
| id                  | Automation ID                       |
| create\_time        | Date created                        |
| status              | Active, paused, or draft            |
| emails\_sent        | Total sends across the automation   |
| start\_time         | When the automation started running |
| recipients.list\_id | Audience the automation targets     |

## Common metric combinations

* **Campaign performance dashboard** — Campaigns report + Audience growth history, joined on `list_id`, shows how list health correlates with campaign results
* **Contact engagement analysis** — Audience (list of contacts) + Audience activity, joined on `email_address`, reveals which subscribers are most active
* **Multi-audience rollup** — Append the Audience growth history from multiple audiences to compare list growth across segments
* **Automation health check** — Automations + Campaigns report, filtered by automation type, to measure automated email performance

## Use cases by role

{% tabs %}
{% tab title="Email Marketers" %}

* Pull **Campaigns report** into Google Sheets or Looker Studio to build a live campaign performance dashboard
* Track open and click rates over time to identify which subject lines and send times perform best
* Use **Audience growth history** to visualize subscriber trends and report on list health month over month
* Send Campaigns report data to ChatGPT or Claude to generate natural-language summaries of campaign performance
  {% endtab %}

{% tab title="Marketing Analysts" %}

* Join **Campaigns report** with ad spend data from other sources to calculate email's contribution to revenue
* Use **Audience locations** to map geographic engagement and tailor regional campaigns
* Append data from multiple audiences using Coupler.io's Append transformation to create a unified subscriber dataset
* Load data into BigQuery for SQL-based segmentation and cohort analysis
  {% endtab %}

{% tab title="Marketing Ops" %}

* Export **Audience (list of contacts)** regularly to keep your CRM or data warehouse in sync with Mailchimp
* Monitor **Automations** status to audit which workflows are active and how many emails they're sending
* Use the **List of audiences** entity to maintain a master record of all audiences across the account
* Set up an Append data flow to combine contact lists from multiple Mailchimp audiences into a single destination table
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Audience-level entities (contacts, activity, clients, growth, interest categories, locations) require you to select a specific audience — they do not pull across all audiences at once. Use an Append transformation to combine data from multiple audiences.
* The **Campaigns report** entity uses sent date filters (`sentSinceDate` / `sentBeforeDate`). The **Campaigns** entity uses creation date filters instead.
* Mailchimp's API rate limits can cause timeouts for very large audiences (100k+ contacts). If this happens, consider filtering by status or using advanced filters to reduce the dataset size.
* Customer Journey data is not currently available as a Coupler.io entity — this is a known feature request.
* The `member_rating` field in Audience contacts is Mailchimp's built-in engagement score and is updated by Mailchimp, not Coupler.io.

## Mailchimp common issues

### Connection issues

<details>

<summary>OAuth connection fails or account doesn't appear after authorization</summary>

This usually happens when the popup is blocked or you authorized the wrong Mailchimp account. Close the popup, disable any popup blocker for the Coupler.io domain, and try connecting again. Make sure you're logged in to the correct Mailchimp account before clicking Connect — if you have multiple Mailchimp accounts, Mailchimp will use whichever one is currently active in your browser.

</details>

<details>

<summary>My Mailchimp audience doesn't appear in the audience dropdown</summary>

If you've just created a new audience in Mailchimp, try disconnecting and reconnecting your Mailchimp account in Coupler.io to refresh the list. If an audience still doesn't appear, check that your Mailchimp user role has access to that audience — Manager-level access is required.

</details>

### Permission errors

<details>

<summary>Error 403 — access denied</summary>

A 403 error means Coupler.io doesn't have permission to access the requested resource. This typically means your Mailchimp user role is too restricted. Mailchimp's **Viewer** role does not grant API access — you need at least **Manager** access. Ask your Mailchimp account admin to upgrade your role, then reconnect your account in Coupler.io.

</details>

### Missing data

<details>

<summary>Data is missing after a run completes</summary>

First, check that you selected the correct audience in the source settings — each audience-level entity only pulls from one audience at a time. If you're combining data from multiple audiences, you need separate sources in your data flow with the Append transformation applied. Also check whether any date filters are set that might be excluding records.

</details>

<details>

<summary>Some contacts are not appearing in the Audience export</summary>

By default, the **Audience (list of contacts)** entity returns all statuses. If you've applied advanced filters (e.g., filtering by status), some contacts may be excluded. Remove or adjust the advanced filters and re-run. Also note that archived contacts are not returned by the Mailchimp API.

</details>

<details>

<summary>Campaigns report shows different numbers than Mailchimp's dashboard</summary>

Mailchimp updates campaign stats over time as opens and clicks are tracked. If you pull data shortly after sending a campaign, the numbers will be lower than what you'll see after 24–48 hours. Re-run the data flow after the campaign has had time to accumulate engagement data. Also verify that your sent date filters aren't excluding campaigns you expect to see.

</details>

### Rate limits and timeouts

<details>

<summary>Data flow times out after 9 minutes</summary>

This is the most commonly reported issue for Mailchimp. It typically occurs with large audiences (100,000+ contacts) or when pulling the **Audience activity** entity, which can be very large. To work around this:

* Use **advanced filters** on the Audience entity to pull a subset of contacts (e.g., filter by status = subscribed)
* Use **date filters** on Campaigns and Automations to limit the time range
* Split large audiences across multiple data flows using status or tag filters
* For Mailchimp-to-BigQuery flows specifically, contact Coupler.io support — there may be additional options for large dataset handling

</details>

<details>

<summary>Error 409 — conflict error</summary>

A 409 error usually means the data flow ran while a previous run was still in progress, causing a conflict at the destination. Wait for any active run to finish before triggering another, or check if your schedule interval is too frequent for the size of the dataset being pulled.

</details>

## Mailchimp FAQ

<details>

<summary>Can I pull data from multiple Mailchimp audiences into one sheet?</summary>

Yes. Add multiple sources to your data flow — one per audience — each configured with the same entity type but a different audience selected. Then apply the **Append** transformation to combine the rows into a single destination table. This works for contacts, activity, growth history, and other audience-level entities.

</details>

<details>

<summary>Why does my data flow time out when pulling a large audience?</summary>

Mailchimp's API has a 9-minute response window, and large audiences (especially 100,000+ contacts or the Audience activity entity) can exceed this. To fix it, apply advanced filters to pull a subset — for example, filter by `status = subscribed` — or use the Columns setting to reduce the number of fields returned. For Mailchimp-to-BigQuery flows, contact Coupler.io support for guidance on handling very large datasets.

</details>

<details>

<summary>The open and click rates in Coupler.io don't match what I see in Mailchimp — why?</summary>

Mailchimp continues updating campaign stats for days after a send as more recipients open or click. If you pulled data shortly after sending, the numbers will be lower than Mailchimp's dashboard, which shows the latest live figures. Re-run the data flow 24–48 hours after the campaign to get more settled numbers.

</details>

<details>

<summary>Can I get click-level detail — which links were clicked and how many times?</summary>

The **Campaigns report** entity includes aggregate click counts but does not break down clicks by individual link. Link-level click detail is not currently available as a standalone Coupler.io entity for Mailchimp. For this level of detail, you would need to use the Mailchimp API directly or request this as a feature through Coupler.io support.

</details>

<details>

<summary>Is Customer Journey data available?</summary>

Not yet. Customer Journeys is a frequently requested feature but is not currently supported as a Mailchimp entity in Coupler.io. You can submit a feature request via Coupler.io support to register your interest.

</details>

<details>

<summary>Can I filter contacts by tag or custom field?</summary>

Yes. When you select the **Audience (list of contacts)** entity, use the **Advanced filters** setting to filter by status, tag, or other contact properties. This is also the recommended approach for keeping run times short on large lists.

</details>

<details>

<summary>I get a 403 error when trying to pull audience data — how do I fix it?</summary>

A 403 error means your Mailchimp account doesn't have sufficient permissions. Mailchimp's Viewer role does not allow API access. Ask your Mailchimp admin to grant you at least **Manager** access, then disconnect and reconnect your Mailchimp account in Coupler.io.

</details>

<details>

<summary>Can I automate a Mailchimp export to Excel or BigQuery, not just Google Sheets?</summary>

Yes. Coupler.io supports Excel (via OneDrive or SharePoint), BigQuery, Google Sheets, Looker Studio, and AI destinations like ChatGPT, Claude, Gemini, Perplexity, and Cursor. Select your preferred destination when setting up the data flow.

</details>

<details>

<summary>Why don't I see all my Mailchimp audiences in the dropdown?</summary>

If a recently created audience isn't showing, try disconnecting and reconnecting your Mailchimp account in Coupler.io to refresh the list. If an audience is still missing, check that your Mailchimp user role has access to it — some audiences may be restricted by role or team settings in your Mailchimp account.

</details>

{% hint style="info" %}
For a full breakdown of available fields and metrics per entity, see the [Data Overview](#mailchimp-data-overview) article. For connection errors and timeout fixes, see [Common Issues](#mailchimp-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/marketing/mailchimp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
