Skip to main content


This page guides you through setting up the Mailchimp source connector.


For Airbyte Cloud

  • Access to a valid Mailchimp account. If you are not an Owner/Admin of the account, you must be granted Admin access by the account's Owner/Admin.

For Airbyte Open Source

  • A valid Mailchimp API Key (recommended) or OAuth credentials: Client ID, Client Secret and Access Token

Setup guide

Airbyte Open Source: Generate a Mailchimp API key

  1. Navigate to the API Keys section of your Mailchimp account.
  2. Click Create New Key, and give the key a name to help you identify it. You won't be able to see or copy the key once you finish generating it, so be sure to copy the key and store it in a secure location.

For more information on Mailchimp API Keys, please refer to the official Mailchimp docs. If you want to use OAuth authentication with Airbyte Open Source, please follow the steps laid out here to obtain your OAuth Client ID, Client Secret and Access Token.

Set up the Mailchimp source connector

  1. Log into your Airbyte Cloud or Airbyte Open Source account.
  2. Click Sources and then click + New source.
  3. Find and select Mailchimp from the list of available sources.
  4. Enter a name for your source.
  5. You can use OAuth or an API key to authenticate your Mailchimp account. We recommend using OAuth for Airbyte Cloud and an API key for Airbyte Open Source.
  • To authenticate using OAuth for Airbyte Cloud, click Authenticate your Mailchimp account and follow the instructions to sign in with Mailchimp and authorize your account.
  • To authenticate using an API key for Airbyte Open Source, select API key from the Authentication dropdown and enter the API key for your Mailchimp account.
  • To authenticate using OAuth credentials, select Oauth2.0 from the dropdown and enter the Client ID, Client Secret and Access Token you obtained.
  1. (Optional) You may optionally provide an Incremental Sync Start Date using the provided datepicker, or by programmatically entering a UTC date-time in the format YYYY-MM-DDThh:mm:ss.sssZ. If set, only data generated on or after the configured date-time will be synced. Leaving this field blank will sync all data returned from the API.
  2. Click Set up source and wait for the tests to complete.

Supported streams

The Mailchimp source connector supports the following streams and sync modes:

StreamFull RefreshIncremental
Email Activity
Interest Categories
List Members
Segment Members

A note on primary keys

The EmailActivity and Unsubscribes streams do not have an id primary key, and therefore use the following composite keys as unique identifiers:

  • EmailActivity [email_id, action, timestamp]
  • Unsubscribes [campaign_id, email_id, timestamp]

All other streams contain an id primary key.

Data type mapping

Integration TypeAirbyte TypeNotes
arrayarraythe type of elements in the array is determined based on the mappings in this table
float, numbernumber
objectobjectproperties within objects are mapped based on the mappings in this table
string (timestamp)timestamp_with_timezoneMailchimp timestamps are formatted as YYYY-MM-DDTHH:MM:SS+00:00

Limitations & Troubleshooting

Expand to see details about Mailchimp connector limitations and troubleshooting

Connector limitations

Mailchimp does not impose rate limits on how much data is read from its API in a single sync process. However, Mailchimp enforces a maximum of 10 simultaneous connections to its API, which means that Airbyte is unable to run more than 10 concurrent syncs from Mailchimp using API keys generated from the same account.


Now that you have set up the Mailchimp source connector, check out the following Mailchimp tutorial:


Config fields reference

Property name


Expand to review
VersionDatePull RequestSubject
2.0.62024-06-2139937Update dependencies
2.0.52024-06-1838868Refactor: use client_side_incremental feature
2.0.42024-06-0639202[autopull] Upgrade base image to v1.2.2
2.0.32024-05-0236649Schema descriptions
2.0.22024-04-2537572Fixed start_date format issue for the email_activity stream
2.0.12024-04-1937434Fixed cursor format for the email_activity stream
2.0.02024-04-0135281Migrate to Low-Code
1.2.02024-03-2836600Migrate to latest Airbyte-CDK.
1.1.22024-02-0935092Manage dependencies with Poetry.
1.1.12024-01-1134157Prepare for airbyte-lib
1.1.02023-12-2032852Add optional start_date for incremental streams
1.0.02023-12-1932836Add airbyte-type to datetime columns and remove ._links column
0.10.02023-11-2332782Add SegmentMembers stream
0.9.02023-11-1732218Add Interests, InterestCategories, Tags streams
0.8.32023-11-1532543Handle empty datetime fields in Reports stream
0.8.22023-11-1332466Improve error handling during connection check
0.8.12023-11-0632226Unmute expected records test after data anonymisation
0.8.02023-11-0132032Add ListMembers stream
0.7.02023-10-2731940Implement availability strategy
0.6.02023-10-2731922Add Segments stream
0.5.02023-10-2031675Add Unsubscribes stream
0.4.12023-05-0225717Handle unknown error in EmailActivity
0.4.02023-04-1123290Add Automations stream
0.3.52023-02-2823464Add Reports stream
0.3.42023-02-0622405Revert extra logging
0.3.32023-02-0122228Add extra logging
0.3.22023-01-2722014Set AvailabilityStrategy for streams explicitly to None
0.3.12022-12-2020720Use stream slices as a source for request params instead of a stream state
0.3.02022-11-0719023Set primary key for Email Activity stream.
0.2.152022-09-2817326Migrate to per-stream states.
0.2.142022-04-1211352Update documentation
0.2.132022-04-1111632Add unit tests
0.2.122022-03-1710975Fix campaign's stream normalization
0.2.112021-12-247159Add oauth2.0 support
0.2.102021-12-219000Update connector fields title/description
0.2.92021-12-137975Updated JSON schemas
0.2.82021-08-175481Remove date-time type from some fields
0.2.72021-08-035137Source Mailchimp: fix primary key for email activities
0.2.62021-07-285024Source Mailchimp: handle records with no no "activity" field in response
0.2.52021-07-084621Mailchimp fix url-base
0.2.42021-06-094285Use datacenter URL parameter from apikey
0.2.32021-06-083973Add AIRBYTE_ENTRYPOINT for Kubernetes support
0.2.22021-06-083415Get Members activities
0.2.12021-04-032726Fix base connector versioning
0.2.02021-03-092238Protocol allows future/unknown properties
0.1.42020-11-301046Add connectors using an index YAML file