You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/connections/destinations/catalog/mailchimp/index.md
+47-25Lines changed: 47 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,23 @@
1
1
---
2
2
rewrite: true
3
+
hide-personas-partial: true
3
4
title: Mailchimp Destination
4
5
id: 54521fd925e721e32a72eed3
5
6
---
6
-
[Mailchimp](https://mailchimp.com/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners) provides email marketing automation for e-commerce businesses. With Segment you can add people to your MailChimp list with a single [`identify`](/docs/connections/spec/identify/) call.
7
+
[Mailchimp](https://mailchimp.com/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners){:target="_blank"} provides email marketing automation for e-commerce businesses. With Segment you can add people to your Mailchimp list with a single [`identify`](/docs/connections/spec/identify/) call.
7
8
8
9
9
-
## Getting Started
10
+
## Getting started
10
11
11
12
{% include content/connection-modes.md %}
12
13
13
-
1. From the Segment web app, click **Catalog**.
14
-
2. Search for "MailChimp" in the Catalog, select it, and choose which of your sources to connect the destination to.
15
-
3. In the destination settings, enter your MailChimp "API key" into the connection settings.
16
-
You should create a 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 ensures maximum throughput for outgoing calls. You can read more about API keys on [MailChimp's docs](http://kb.mailchimp.com/integrations/api-integrations/about-api-keys).
17
-
4. Enter your MailChimp "[Audience ID](#audience-id)" into the connection settings.
18
-
5. Enter your MailChimp "[Datacenter ID](#datacenter-id)" into the connection settings.
14
+
1. From the Segment web app, navigate to **Connections > Catalog** and go to the **Destinations** tab of the catalog.
15
+
2. Search for *Mailchimp*, select it, and click **Configure Mailchimp**.
16
+
3. Choose the source to connect the destination to.
17
+
4. In the destination settings, enter your Mailchimp "API key" into the connection settings.
18
+
You should create a 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 ensures maximum throughput for outgoing calls. You can read more about API keys on [Mailchimp's docs](http://kb.mailchimp.com/integrations/api-integrations/about-api-keys){:target="_blank"}.
19
+
4. Enter your Mailchimp "[Audience ID](#audience-id)" into the connection settings.
20
+
5. Enter your Mailchimp "[Datacenter ID](#datacenter-id)" into the connection settings.
Every time you call [identify](/docs/connections/spec/identify/) with an email address included, we will:
34
+
Every time you call [identify](/docs/connections/spec/identify/) with an email address included, Segment:
33
35
34
-
1. First ask Mailchimp if that email exists and what their subscriber status is for the `listId` you have provided in the destination settings.
36
+
1. First asks Mailchimp if that email exists and what their subscriber status is for the `listId` you've provided in the destination settings.
35
37
36
-
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`.
38
+
2. If they don't exist, Segment **subscribes** that user to the list immediately. If you enabled the `doubleOptIn` setting, it sends a confirmation email to that user before subscribing them, and that email won't be tagged with a subscriber status of `pending`.
37
39
38
-
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`.
40
+
3. If they already have a subscriber status such as `pending`, `subscribed`, `unsubscribed`, or `cleaned`, Segment doesn't resubscribe them, but updates their user `traits`.
39
41
40
42
So you no longer have to worry about the `identify` call resubscribing users unintentionally!
41
43
42
-
Segment recognizes `firstName`, `lastName` and `email` as [special traits](/docs/connections/spec/identify#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.
44
+
Segment recognizes `firstName`, `lastName`, and `email` as [special traits](/docs/connections/spec/identify#traits), so Segment translates those for you to match the Mailchimp accepted field names. Mailchimp includes these fields by default when you create a list.
43
45
44
-
### Recording Custom User Traits
46
+
### Recording custom user traits
45
47
46
-
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](#custom-merge-fields) 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.
48
+
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](#custom-merge-fields) of the `traits` in your `identify` calls. Note that you don't need to map all `user.traits` you're sending inside Mailchimp. You only need to create custom merge fields of the traits you *want* to see in your list view.
47
49
48
-
**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).
50
+
> warning ""
51
+
> **IMPORTANT:** Mailchimp only supports merge tags that are 10 characters or shorter. For every user `trait` you send inside the `.identify()` call, Segment will trim it to be the first 10 characters and will send it in **uppercase** form to Mailchimp.
49
52
50
-
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.
53
+
54
+
It's 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).
51
55
52
-
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.
56
+
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 Segment converts that to `WAYTOOLONG` before sending it to Mailchimp.
57
+
58
+
If you're going to send 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 Segment will stringify all `boolean` or `null` objects to strings.
53
59
54
60
Also note that fields you specify in Mailchimp as date fields must receive dates. Passing non-date values will cause issues.
55
61
56
-
### Custom Merge Fields
62
+
### Custom merge fields
57
63
58
64
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 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.
82
+
For any other custom `traits`, add a Mailchimp custom merge field inside of Mailchimp with a tag that matches the key you're 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 populate.
77
83
78
-
One thing to note is that you shouldn't use underscores in your custom Merge Field names.
84
+
> success ""
85
+
> Don't use underscores in your custom merge field names. When Segment maps to Mailchimp merge fields, Segment removes the underscores and capitalizes the entire field.
79
86
80
87
Once Mailchimp has processed the new subscriber you'll see it show up in your list, like this:
To record a Segment `userId` in Mailchimp, you must pass the userID as a trait on your `identify()` calls. We do not automatically map the Segment userID to any Mailchimp properties.
93
+
To record a Segment `userId` in Mailchimp, you must pass the userID as a trait on your `identify()` calls. Segment doesn't automatically map the userID to any Mailchimp properties.
87
94
88
95
### Overriding List ID (Also now referred to as Audience ID)
**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).
126
+
> warning ""
127
+
> **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).
120
128
121
129
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.
122
130
123
131
## Troubleshooting
124
132
125
-
### Why are my calls with trait arrays not showing up in MailChimp?
126
-
MailChimp does not support arrays as traits values. This can cause calls to not show up.
133
+
### Why are my calls with trait arrays not showing up in Mailchimp?
134
+
Mailchimp doesn't support arrays as traits values. This can cause calls to not show up.
135
+
136
+
## Engage
137
+
138
+
You can send computed traits and audiences generated using [Engage](/docs/engage/) to Mailchimp as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/demo/){:target="_blank"}.
139
+
140
+
> success ""
141
+
> Before creating audiences or computed traits with Engage, you must first create merge fields in Mailchimp. Learn more about [recording custom user traits](#recording-custom-user-traits) and [sending custom merge fields](#custom-merge-fields) to Mailchimp.
142
+
143
+
For user-property destinations, an [identify call](/docs/connections/spec/identify/) is sent to the destination for each user being added and removed. The property name is the snake_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it’s been more than 30 days since their last order), Engage sets that value to `false`.
144
+
145
+
When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.
146
+
147
+
> info "Real-time to batch destination sync frequency"
148
+
> Real-time audience syncs to Mailchimp may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two or three hours is expected.
0 commit comments