MailChimp Destination

Segment makes it easy to send your data to MailChimp (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to MailChimp in the format they understand. Learn more about how to use MailChimp with Segment.

With Segment you can add people to your Mailchimp list with a single identify call.

Getting Started

Creating your API Key

It is recommended that you create a brand new api key for the Segment destination. MailChimp restricts each api key to a maximum of 10 concurrent requests, so creating a dedicated one for Segment will ensure maximum throughput for outgoing calls.

You can read more about API keys on MailChimp’s docs.

Finding your List ID

Select the list you wish to add users to, then look in “Settings” under “List Name & defaults”. Your List Id will be at the top of the right column, here:

Finding your List ID


Every time you call identify with an email address included, we will:

  • 1) First ask Mailchimp if that email exists and what their subscriber status is for the listId you have provided in the destination settings.

  • 2) If they do not exist, we will subscribe that user to the list immediately. If you have doubleOptIn setting enabled, it will send a confirmation email to that user before subscribing them and that email will not be tagged with a subscriber status of pending.

  • 3) If they already have a subscriber status such as pending, subscribed, unsubscribed or cleaned, we will NOT resubscribe them but simply update their user traits.

So you no longer have to worry about the identify call resubscribing users unintentionally!

Here’s an example:

Segment recognizes firstName, lastName and email as special traits, so we will translate those for you to match the Mailchimp accepted field names. Mailchimp includes these fields by default when you create a list.

Recording Custom User Traits

If you want to view any other custom user traits in the Mailchimp list dashboard, you must create a Custom Merge Field inside Mailchimp’s UI of the traits in your identify calls. Note that you do not need to map all user.traits you are sending inside Mailchimp. You only need to create Custom Merge Fields of the traits you want to see in your list view.

IMPORTANT: Mailchimp only supports merge tags that are 10 characters or shorter. So for every user trait you send inside the .identify() call, we will trim it to be the first 10 characters and will send it in uppercase form to Mailchimp. So it’s very important that when you set up your merge tags in Mailchimp, your Merge Tags are the first 10 characters (excluding whitespace or special characters) of its Field Label (if it’s over 10 characters).

For example, if your Field Label was Way Too-Long123, your Merge Tag should be WAYTOOLONG. And the user.trait inside your .identify() call would be Way Too-Long123 since we will convert that to WAYTOOLONG before sending it to Mailchimp.

If you are going to be sending either a boolean or null object as a user.trait value, when creating the custom merge field for that trait inside Mailchimp, make sure to set the data type as TEXT since we will stringify all boolean or null objects to strings.

Also note that fields you specify in Mailchimp as date fields must receive dates. Passing non-date values will cause issues.

Recording userId

If you send a userId in your .identify() call, we will attach it as Mailchimp’s semantic unique_email_id for that user. This is a read-only unique identifier for that email across all of Mailchimp.

Overriding List ID

If you have multiple lists that your users can subscribe to, you can override the default list ID. Simply send a listId parameter as an option for Mailchimp:

analytics.identify('12345', {
  firstName: 'Peter'
  }, {
    "MailChimp": {
      "listId": "ea7918abb6"

Manually updating user subscription status

If you’d like to manually update a user’s subscription status, you can do so by passing in subscriptionStatus property as an option for Mailchimp:

analytics.identify('12345', {
  firstName: 'Peter'
  }, {
    "MailChimp": {
      "listId": "ea7918abb6",
      "subscriptionStatus": "unsubscribed"

Important: You must use the semantic property exactly as is, subscriptionStatus (case-sensitive) and the value of this property must be one of the four valid statuses supported by Mailchimp: pending, subscribed, unsubscribed, and cleaned (all lowercase).

Again, this will NOT work for new users. New users will always have their subscription status set as either pending or subscribed depending on your double opt-in setting.


Custom Merge Fields

To send custom merge fields/user traits to Mailchimp you need to create the merge field first in Mailchimp for each trait you want sent to Mailchimp. Then when you call identify with keys that match those traits they will appear in your Mailchimp list.

For example, if you have a list in Mailchimp with these custom merge fields:

mailchimp merge fields screenshot

You can populate those fields using this identify call:

For any other custom traits just add a Mailchimp Custom Merge Field inside of Mailchimp with a tag that matches the key you are using in your identify call. In the example these traits are company and employees. They will be shown as COMPANY and EMPLOYEES in Mailchimp, but you can record them in lower-case to identify and they will still be populated.

Once Mailchimp has processed the new subscriber you’ll see it show up in your list, like this:

mailchimp subscriber screenshot


Note that you can’t pass arrays as values to Mailchimp. This can cause calls to not show up.

Supported Sources and Connection Modes

📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.


Segment lets you change these destination settings via your Segment dashboard without having to touch any code.


You create and copy-paste your MailChimp API Key from Account Settings > Extras > API Keys.

Datacenter ID

You can find your Datacenter ID in the MailChimp url in your browser when you’re logged in. It’s the ‘us1’ in ‘‘.

Double Opt-In

An optional flag to control whether a double opt-in confirmation message is sent when subscribing new users.

List ID

You can find your List ID in your Mailchimp list’s Settings pane under List Name & Defaults. Your list ID will be at the top of the right column.

If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!