Mailchimp
Use this guide to set up the Mailchimp source connector.
Prerequisites
Airbyte Cloud
- You need access to a valid Mailchimp account. If you aren’t an Owner/Admin, the account’s Owner/Admin must granted Admin access you.
Airbyte Open Source
- You need a valid Mailchimp API Key (recommended) or these OAuth credentials: Client ID, Client Secret and Access Token
Setup guide
Generate a Mailchimp API key
- Go to the API Keys section of your Mailchimp account.
- Click Create New Key and name the key so you can identify it. You can’t view or copy the key after generating it. Copy the key and store it securely before you finish.
For more information about Mailchimp API Keys, see the official Mailchimp docs. To use OAuth with Airbyte Open Source, follow here to obtain your OAuth Client ID, Client Secret and Access Token.
Set up the connector
- Log in to your Airbyte Cloud or Airbyte Open Source account.
- Click Sources, then click + New source.
- Find and select Mailchimp from the available sources.
- Enter a name for your source.
- Authenticate your Mailchimp account using OAuth or an API key. OAuth is recommended for Airbyte Cloud, while an API key is recommended for Airbyte Open Source.
- For Airbyte Cloud OAuth, click Authenticate your Mailchimp account. Follow the instructions to sign in with Mailchimp and authorise your account.
- For Airbyte Open Source API key authentication, select API key from the Authentication dropdown. Enter the API key for your Mailchimp account.
- For OAuth authentication, select Oauth2.0 from the dropdown. Enter the Client ID, Client Secret and Access Token you obtained.
- (Optional) Set an Incremental Sync Start Date using the datepicker or enter a UTC date-time programmatically in the format
YYYY-MM-DDThh:mm:ss.sssZ. Only data generated on or after this date-time will sync. Leave the field blank to sync all data returned by the API. - Click Set up source and wait for the tests to finish.
Supported streams
The Mailchimp source connector supports these streams and sync modes:
| Stream | Full Refresh | Incremental |
|---|---|---|
| Automations | ✓ | ✓ |
| Campaigns | ✓ | ✓ |
| Email Activity | ✓ | ✓ |
| Interests | ✓ | |
| Interest Categories | ✓ | |
| Lists | ✓ | ✓ |
| List Members | ✓ | ✓ |
| Reports | ✓ | ✓ |
| Segments | ✓ | ✓ |
| Segment Members | ✓ | ✓ |
| Tags | ✓ | |
| Unsubscribes | ✓ | ✓ |
Primary keys
The EmailActivity and Unsubscribes streams don’t have an id primary key. They use these composite keys as unique identifiers:
- EmailActivity [
email_id,action,timestamp] - Unsubscribes [
campaign_id,email_id,timestamp]
Every other stream contains an id primary key.
Data type mapping
| Integration Type | Airbyte Type | Notes |
|---|---|---|
array | array | the type of elements in the array is determined based on the mappings in this table |
string | string | |
float, number | number | |
integer | integer | |
object | object | properties within objects are mapped based on the mappings in this table |
string (timestamp) | timestamp_with_timezone | Mailchimp timestamps are formatted as YYYY-MM-DDTHH:MM:SS+00:00 |
Limitations and troubleshooting
Expand for details about Mailchimp connector limitations and troubleshooting
Connector limitations
The Mailchimp Marketing API allows up to 10 simultaneous connections per account. Exceeding this limit returns an HTTP 429 error. The limit covers all API consumers sharing the account. These include Airbyte syncs, other integrations and the Mailchimp web application. Individual API requests also have a 120-second timeout.
The connector’s Number of concurrent threads configuration parameter controls the number of concurrent syncing threads. Its default is 2, its minimum is 2 and its maximum is 10. You can increase this value to speed up syncs. Keep simultaneous connections across all consumers within Mailchimp’s 10-connection limit.
Tutorials
After setting up the Mailchimp source connector, follow this Mailchimp tutorial:
IP allow list
If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 2.1.45 | 2026-11-10 | 91611 | Update dependencies |
| 2.1.44 | 2026-11-03 | 90647 | Update dependencies |
| 2.1.43 | 2026-10-27 | 89974 | Update dependencies |
| 2.1.42 | 2026-10-20 | 89293 | Update dependencies |
| 2.1.41 | 2026-10-13 | 88715 | Update dependencies |
| 2.1.40 | 2026-10-06 | 87927 | Update dependencies |
| 2.1.39 | 2026-09-29 | 87251 | Update dependencies |
| 2.1.38 | 2026-09-22 | 86698 | Update dependencies |
| 2.1.37 | 2026-09-15 | 86114 | Update dependencies |
| 2.1.36 | 2026-09-08 | 85559 | Update dependencies |
| 2.1.35 | 2026-08-18 | 84660 | Update dependencies |
| 2.1.34 | 2026-08-11 | 84003 | Update dependencies |
| 2.1.33 | 2026-07-28 | 82984 | Update dependencies |
| 2.1.32 | 2026-07-21 | 82491 | Update dependencies |
| 2.1.31 | 2026-07-14 | 81912 | Update dependencies |
| 2.1.30 | 2026-06-30 | 81135 | Update dependencies |
| 2.1.29 | 2026-06-23 | 80520 | Update dependencies |
| 2.1.28 | 2026-06-16 | 79931 | Update dependencies |
| 2.1.27 | 2026-06-09 | 79396 | Update dependencies |
| 2.1.26 | 2026-06-02 | 78809 | Update dependencies |
| 2.1.25 | 2026-04-28 | 77289 | Update dependencies |
| 2.1.24 | 2026-04-21 | 76663 | Update dependencies |
| 2.1.23 | 2026-04-17 | 76453 | Promoted release candidate to GA |
| 2.1.23-rc.4 | 2026-04-13 | 76268 | Add HTTPAPIBudget for rate limit enforcement (Phase 2 of concurrency tuning) |
| 2.1.23-rc.3 | 2026-04-10 | 76232 | Increase default_concurrency to 6 (iteration 3, final concurrency tuning) |
| 2.1.23-rc.2 | 2026-04-08 | 70860 | Increase default_concurrency to 5 (iteration 2 of concurrency tuning) |
| 2.1.23-rc.1 | 2026-04-08 | 70860 | Add concurrency_level and num_workers configuration for concurrency tuning |
| 2.1.22 | 2026-04-01 | 75576 | Add oauth_connector_input_specification for declarative OAuth |
| 2.1.21 | 2026-03-31 | 75803 | Update dependencies |
| 2.1.20 | 2026-03-24 | 74579 | Update dependencies |
| 2.1.19 | 2026-03-03 | 74155 | Update dependencies |
| 2.1.18 | 2026-02-17 | 73380 | Update dependencies |
| 2.1.17 | 2026-02-10 | 73055 | Update dependencies |
| 2.1.16 | 2026-01-20 | 72019 | Update dependencies |
| 2.1.15 | 2026-01-14 | 71446 | Update dependencies |
| 2.1.14 | 2025-12-18 | 70791 | Update dependencies |
| 2.1.13 | 2025-11-25 | 70012 | Update dependencies |
| 2.1.12 | 2025-11-18 | 69453 | Update dependencies |
| 2.1.11 | 2025-10-29 | 68941 | Update dependencies |
| 2.1.10 | 2025-10-21 | 68319 | Update dependencies |
| 2.1.9 | 2025-10-14 | 68062 | Update dependencies |
| 2.1.8 | 2025-10-07 | 67516 | Update dependencies |
| 2.1.7 | 2025-09-30 | 66812 | Update dependencies |
| 2.1.6 | 2025-09-24 | 66653 | Update dependencies |
| 2.1.5 | 2025-09-09 | 66042 | Update dependencies |
| 2.1.4 | 2025-08-26 | 65557 | Update dependencies |
| 2.1.3 | 2025-08-23 | 65361 | Update dependencies |
| 2.1.2 | 2025-08-09 | 64625 | Update dependencies |
| 2.1.1 | 2025-08-02 | 61114 | Update dependencies |
| 2.1.0 | 2025-07-21 | 63702 | Promoting release candidate 2.1.0-rc.1 to a main version. |
| 2.1.0-rc.1 | 2025-07-15 | 62868 | Migrate to manifest-only format |
| 2.0.37 | 2025-05-24 | 60659 | Update dependencies |
| 2.0.36 | 2025-05-10 | 59273 | Update dependencies |
| 2.0.35 | 2025-04-26 | 58815 | Update dependencies |
| 2.0.34 | 2025-04-12 | 57719 | Update dependencies |
| 2.0.33 | 2025-04-05 | 57043 | Update dependencies |
| 2.0.32 | 2025-03-29 | 56034 | Update dependencies |
| 2.0.31 | 2025-03-08 | 55471 | Update dependencies |
| 2.0.30 | 2025-03-01 | 54795 | Update dependencies |
| 2.0.29 | 2025-02-22 | 54366 | Update dependencies |
| 2.0.28 | 2025-02-15 | 53836 | Update dependencies |
| 2.0.27 | 2025-02-01 | 52730 | Update dependencies |
| 2.0.26 | 2025-01-25 | 52236 | Update dependencies |
| 2.0.25 | 2025-01-11 | 51215 | Update dependencies |
| 2.0.24 | 2025-01-04 | 50894 | Update dependencies |
| 2.0.23 | 2024-12-28 | 50633 | Update dependencies |
| 2.0.22 | 2024-12-21 | 50139 | Update dependencies |
| 2.0.21 | 2024-12-14 | 49148 | Update dependencies |
| 2.0.20 | 2024-11-22 | 45282 | Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64 |
| 2.0.19 | 2024-08-31 | 45031 | Update dependencies |
| 2.0.18 | 2024-08-24 | 44708 | Update dependencies |
| 2.0.17 | 2024-08-17 | 44323 | Update dependencies |
| 2.0.16 | 2024-08-12 | 43752 | Update dependencies |
| 2.0.15 | 2024-08-10 | 43554 | Update dependencies |
| 2.0.14 | 2024-08-03 | 43228 | Update dependencies |
| 2.0.13 | 2024-07-27 | 42683 | Update dependencies |
| 2.0.12 | 2024-07-20 | 42381 | Update dependencies |
| 2.0.11 | 2024-07-13 | 41683 | Update dependencies |
| 2.0.10 | 2024-07-10 | 41399 | Update dependencies |
| 2.0.9 | 2024-07-09 | 41152 | Update dependencies |
| 2.0.8 | 2024-07-06 | 40897 | Update dependencies |
| 2.0.7 | 2024-06-25 | 40320 | Update dependencies |
| 2.0.6 | 2024-06-21 | 39937 | Update dependencies |
| 2.0.5 | 2024-06-18 | 38868 | Refactor: use client_side_incremental feature |
| 2.0.4 | 2024-06-06 | 39202 | [autopull] Upgrade base image to v1.2.2 |
| 2.0.3 | 2024-05-02 | 36649 | Schema descriptions |
| 2.0.2 | 2024-04-25 | 37572 | Fixed start_date format issue for the email_activity stream |
| 2.0.1 | 2024-04-19 | 37434 | Fixed cursor format for the email_activity stream |
| 2.0.0 | 2024-04-01 | 35281 | Migrate to Low-Code |
| 1.2.0 | 2024-03-28 | 36600 | Migrate to latest Airbyte-CDK. |
| 1.1.2 | 2024-02-09 | 35092 | Manage dependencies with Poetry. |
| 1.1.1 | 2024-01-11 | 34157 | Prepare for airbyte-lib |
| 1.1.0 | 2023-12-20 | 32852 | Add optional start_date for incremental streams |
| 1.0.0 | 2023-12-19 | 32836 | Add airbyte-type to datetime columns and remove ._links column |
| 0.10.0 | 2023-11-23 | 32782 | Add SegmentMembers stream |
| 0.9.0 | 2023-11-17 | 32218 | Add Interests, InterestCategories, Tags streams |
| 0.8.3 | 2023-11-15 | 32543 | Handle empty datetime fields in Reports stream |
| 0.8.2 | 2023-11-13 | 32466 | Improve error handling during connection check |
| 0.8.1 | 2023-11-06 | 32226 | Unmute expected records test after data anonymisation |
| 0.8.0 | 2023-11-01 | 32032 | Add ListMembers stream |
| 0.7.0 | 2023-10-27 | 31940 | Implement availability strategy |
| 0.6.0 | 2023-10-27 | 31922 | Add Segments stream |
| 0.5.0 | 2023-10-20 | 31675 | Add Unsubscribes stream |
| 0.4.1 | 2023-05-02 | 25717 | Handle unknown error in EmailActivity |
| 0.4.0 | 2023-04-11 | 23290 | Add Automations stream |
| 0.3.5 | 2023-02-28 | 23464 | Add Reports stream |
| 0.3.4 | 2023-02-06 | 22405 | Revert extra logging |
| 0.3.3 | 2023-02-01 | 22228 | Add extra logging |
| 0.3.2 | 2023-01-27 | 22014 | Set AvailabilityStrategy for streams explicitly to None |
| 0.3.1 | 2022-12-20 | 20720 | Use stream slices as a source for request params instead of a stream state |
| 0.3.0 | 2022-11-07 | 19023 | Set primary key for Email Activity stream. |
| 0.2.15 | 2022-09-28 | 17326 | Migrate to per-stream states. |
| 0.2.14 | 2022-04-12 | 11352 | Update documentation |
| 0.2.13 | 2022-04-11 | 11632 | Add unit tests |
| 0.2.12 | 2022-03-17 | 10975 | Fix campaign’s stream normalization |
| 0.2.11 | 2021-12-24 | 7159 | Add oauth2.0 support |
| 0.2.10 | 2021-12-21 | 9000 | Update connector fields title/description |
| 0.2.9 | 2021-12-13 | 7975 | Updated JSON schemas |
| 0.2.8 | 2021-08-17 | 5481 | Remove date-time type from some fields |
| 0.2.7 | 2021-08-03 | 5137 | Source Mailchimp: fix primary key for email activities |
| 0.2.6 | 2021-07-28 | 5024 | Source Mailchimp: handle records with no no “activity” field in response |
| 0.2.5 | 2021-07-08 | 4621 | Mailchimp fix url-base |
| 0.2.4 | 2021-06-09 | 4285 | Use datacenter URL parameter from apikey |
| 0.2.3 | 2021-06-08 | 3973 | Add AIRBYTE_ENTRYPOINT for Kubernetes support |
| 0.2.2 | 2021-06-08 | 3415 | Get Members activities |
| 0.2.1 | 2021-04-03 | 2726 | Fix base connector versioning |
| 0.2.0 | 2021-03-09 | 2238 | Protocol allows future/unknown properties |
| 0.1.4 | 2020-11-30 | 1046 | Add connectors using an index YAML file |