Mailchimp Destination
Mailchimp provides email marketing automation for e-commerce businesses. With Segment you can add people to your MailChimp list with a single identify
call.
This document was last updated on May 08, 2018. If you notice any gaps, out-dated information or simply want to leave some feedback to help us improve our documentation, please let us know!
Use Cases
Getting Started
The first step is to make sure MailChimp supports the source type and connection mode you’ve chosen to implement. You can learn more about what dictates the connection modes we support here.
Web | Mobile | Server | |
---|---|---|---|
📱 Device-mode | |||
☁️ Cloud-mode | ✅ | ✅ | ✅ |
- From your Segment UI’s Destinations page click on “Add Destination”.
- Search for “MailChimp” within the Destinations Catalog and confirm the Source you’d like to connect to.
- Drop in your MailChimp “API key” into the connection settings. 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.
- Drop in your MailChimp “Audience ID” into your connection settings.
- Drop in your MailChimp “Datacenter ID“into your connection settings.
Identify
If you haven’t had a chance to review our spec, please take a look to understand what the Identify method does. An example call would look like:
analytics.identify('userId12345', {
firstName: 'Bob',
lastName: 'Dole',
email: 'bob.dole@initech.com'
});
Every time you call identify with an email address included, we will:
-
First ask Mailchimp if that email exists and what their subscriber status is for the
listId
you have provided in the destination settings. -
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 ofpending
. -
If they already have a subscriber status such as
pending
,subscribed
,unsubscribed
orcleaned
, we will NOT resubscribe them but simply update their usertraits
.
So you no longer have to worry about the identify
call resubscribing users unintentionally!
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.
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:
You can populate those fields using this identify
call:
analytics.identify('userId12345', {
firstName: 'Bob',
lastName: 'Dole',
email: 'bob.dole@initech.com',
company: 'Initech',
employees: 234
});
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.
One thing to note is that you shouldn’t use underscores in your custom Merge Field names.
Once Mailchimp has processed the new subscriber you’ll see it show up in your list, like this:
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 (Also now referred to as Audience ID)
If you have multiple lists (audiences) that your users can subscribe to, you can override the default list (audience) ID. Simply send a listId
parameter as an option for Mailchimp:
analytics.identify('userId12345', {
firstName: 'Bob'
}, {
"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('userId12345', {
firstName: 'Bob'
}, {
integrations: {
"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.
Troubleshooting
Why are my calls with trait arrays not showing up in MailChimp?
MailChimp does not support arrays as traits values. This can cause calls to not show up.
Personas
You can send computed traits and audiences generated through Segment Personas to this destination as a user property. To learn more about Personas, reach out for a demo.
For user-property destinations, an identify call will be sent to the destination for each user being added and removed. The property name will be the snake_cased version of the audience name you provide with a true/false value. For example, when a user first completes an order in the last 30 days, we will send an identify call with the property order_completed_last_30days: true
, and when this user no longer satisfies we will set that value to false
.
When the audience is first created an identify call is sent for every user in the audience. Subsequent syncs will only send updates for those users which were added or removed since the last sync.
Settings
Segment lets you change these destination settings from your Segment dashboard without having to touch any code.
API Key
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 ‘https://us1.admin.mailchimp.com/lists/’.
Double Opt-In
An optional flag to control whether a double opt-in confirmation message is sent when subscribing new users.
Audience ID
You can find your Audience ID in your Mailchimp Settings pane under the Audiences tab. Go to Manage Audiences > Settings and click on Audience Name & Defaults. The Audience ID will be on the right side.
Need support?
Questions? Problems? Need more info? Contact us, and we can help!