Mailchimp Email Integration

Mailchimp Email Integration Guide

OVERVIEW

Humanitru Alpine offers deep integrations with best-in-class email marketing platforms to assist you in all of your email engagement needs. This guide is meant to provide an overview of what goes on behind the scenes, taken directly from the code to ensure that nothing goes missing and undocumented.

To the best of our ability, we will ensure that all email marketing integrations behave similarly. However, as this is a guide specifically for Mailchimp, we will use language that is appropriate to that platform.

Vocabulary

This guide assumes an intermediate level of understanding of the Mailchimp platform and its vocabulary. To provide in brief, within Mailchimp, your contacts belong to Audiences (formerly called Lists), with the potential for your account to have multiple Audiences. Contacts can potentially belong to multiple Audiences, however according to Mailchimp pricing policy, you may be double-charged if the same contact appears in multiple Audiences. If you have set up a newsletter sign up form on your website, chances are that it is directly connected to one, specific Mailchimp Audience.

Within an Audience, you can have Tags (formerly called Static Segments) which you can use to segment contacts. Contacts may have multiple Tags, and Tags can have multiple Contacts.

Furthermore, within an Audience you can have Merge Fields (custom fields) that can be used when personalizing content, e.g. first name, last name, etc. Mailchimp’s preferred syntax for denoting these Merge Fields is with an asterisk, vertical bar, the field name, vertical bar, asterisk, e.g. *|FIRST_NAME|*. This syntax is unique to Mailchimp.

Finally, within Mailchimp a contact may have several subscription statuses: subscribed, cleaned, pending, archived, etc. Please refer to the Mailchimp documentation for specific definitions of what these contact subscription statuses mean.

SETUP & SETTINGS

Integration Settings

LOCATED UNDER THE “INTEGRATIONS” SECTION UNDER “SETTINGS” ON THE LEFT

There are three relevant Mailchimp-specific settings you can control here.

• Mailchimp Audience (Pull) 
  • This is the Mailchimp Audience that Alpine is configured to pull from, meaning all contacts and email campaigns sent to this particular Audience will be synced into Alpine
• Mailchimp Audience(s) (Push)
  • This is the Mailchimp Audience that Alpine is configured to push to, meaning that all of its Constituents (and related information such as Merge Fields) will be created/matched with contacts in this Audience
• Ignored Email Addresses (Comma Separated)
  • This setting pertains to email addresses that you wish to be ignored when the integration pulls information from Mailchimp. As the information pulled involves both contacts and email subscriber activity (emails sent, opened, links clicked, etc.), any email addresses in this field will be ignored entirely.
  • Use this setting for any contacts within Mailchimp that you do not wish to appear within Alpine. To prevent the opposite, i.e. Constituents within Alpine that you do not wish to be pushed into Mailchimp, use the “Do Not Sync” Tag within Alpine under the Tag Group “[Mailchimp] Subscription Status”.

Synced Merge Fields

IN ALPINE “SETTINGS” UNDER “ALL FIELDS”
Alpine can manage its synced fields with Mailchimp, allowing you to use personalized content and information from your Alpine Constituent Report in your Mailchimp email campaigns. Be sure that you’ve added these columns to your Alpine Constituent Report so that you can use their data in your Mailchimp email.

IN ALPINE “SETTINGS” UNDER “ALL FIELDS”,  click on “SYNC TO EMAIL MARKETING MERGE FIELD” to pull that information into your personalized email. In Mailchimp, in the “Merge Tags” drop down you will find the various fields that you’ve selected in Alpine. 

From your Alpine Constituent Report, you can push the following column information to use as “Merge Fields” in your Mailchimp email.

[Alpine] Last Donation Amount
[Alpine] Last Donation At

[Alpine] Transaction Total Tax
[Alpine] Donation Total Tax Deductible

While creating your email, you’ll find in Mailchimp’s “Merge Tags” drop-down several precalculated merge fields available that do not appear in your Alpine Constituent Reporting Interface. Various pre-selected date ranges are available here for you to choose.

The merge fields available in Mailchimp but not in Alpine are the following:

[Alpine] Last Donation Amount Tax Deductible

[Alpine] Linked Donation Tax Deductible 

 

Here is a complete list of the Merge Tags that are available in MailChimp from your Alpine report:

• [Alpine] Last Donation Amount
• [Alpine] Last Donation At
• [Alpine] This Calendar Year Transaction Total Tax Deductible
• [Alpine] Past Calendar Year Transaction Total Tax Deductible
• [Alpine] Last Donation Amount Tax Deductible
• [Alpine] This Calendar Year Donation Total Tax Deductible
• [Alpine]Past Calendar Year Donation Total Tax Deductible
• [Alpine] This July June Fiscal Year Donation Total Tax Deductible
• [Alpine] Past July June Fiscal Year Donation Total Tax Deductible
• [Alpine] This Calendar Year Linked Donation Total Tax Deductible
• [Alpine] Past Calendar Year Linked Donation Total Tax Deductible
• [Alpine] This July June Fiscal Year Linked Donation Total Tax Deductible
• [Alpine] Past July June Fiscal Year Linked Donation Total Tax Deductible
• [Alpine] Last Donation Fair Market Value
• [Alpine] Membership Payment Count
• [Alpine] Last Membership Payment Amount
• [Alpine] Last Membership Payment At
• [Alpine] Membership Expires At

Nightly Sync

OCCURS EVERY NIGHT RANDOMLY BETWEEN 1:00 AM ET AND 4:59 AM ET. 

Every night, all of your integrations will run, including your Mailchimp email marketing integration. The following is a step-by-step process of what occurs every night when your integration is run, in order, taken directly from the code.

PULLING CONTACTS FROM MAILCHIMP INTO ALPINE

CONTACTS ONLY (EMAIL ADDRESSES + ADDITIONAL INFO)

First, all currently applied subscription status Alpine Tags (under the Tag Group: “[Mailchimp] Subscription Status”) will be deleted (except for “Do Not Sync” and “Deleted (Do Not Sync)”, as they will be immediately subsequently refreshed directly from their source, as described in the following paragraph). Then, Alpine will fetch a list of contacts from the Mailchimp audience configured above under Setup (Mailchimp Audience (Pull)), along with additional information depending on the platform.

Additional Fields
Mailchimp	Corresponding Alpine Field
Email Address (all lowercase)	[Base] Email
First Name (*|FNAME|*)	[Base] Email Salutation
Last Name (*|LNAME|*)	“FNAME LNAME” will be [Base] Name (to combat spam, this will be truncated to 255 characters)
Address Line 1 (*|ADDR1|*)	All address fields combined into [Base] Address (and then geocoded into [Derived] Address Fields)
Address Line 2 (*|ADDR2|*)
City (*|CITY|*)
State Abbreviation (*|STATE|*)
ZIP Code (*|ZIP|*)
Subscription Status	A Tag Group named: [Mailchimp] Subscription Status

Alpine will then attempt to either match these contacts to pre-existing Constituents or create new ones if not present or found. This matching algorithm is standardized across our entire platform: return the first result from the following lists, ordered by priority:

1. Any Constituent with the [Base] Email field equal to the correct value
2. Any Constituent with Custom Fields of type Email (e.g. Secondary Email, Tertiary Email, etc.)
3. Any Constituent with the [Base] Name field equal to “FIRST_NAME LAST_NAME”.

If there are multiple matches within the same type of match (e.g. multiple Constituents with the same [Base] Email field matching the email address given, then it will choose the first Constituent created (lower ID). However, do not rely on this as this is not guaranteed [e.g. merging Constituents will generate a new Constituent with a higher ID than any of its merged Constituents]).

*To ensure first and last names are pulled into Alpine, be sure to turn off first and last name as “required” fields in Mailchimp. 

PUSHING CONTACTS FROM ALPINE INTO MAILCHIMP

CONTACTS ONLY (EMAIL ADDRESSES + ADDITIONAL INFO)

For Mailchimp, Alpine will begin pushing its entire Constituent list to your Mailchimp Audience (as defined above under Setup: Mailchimp Audience (Push)), according to the following process:

1. Take every single Constituent within your Alpine database.
2. Out of those Constituents, remove any that are tagged with the following tags:
   1. • [Mailchimp] Subscription Status: Do Not Sync
      • [Mailchimp] Subscription Status: Deleted (Do Not Sync)
3. Fetch all Mailchimp Merge Fields, looking for those maintained by Alpine (within Mailchimp, these will be merge fields that begin with “[Alpine]”, e.g. “[Alpine] Name” or “[Alpine] Email Salutation”
   1. If these fields do not yet exist, then create them.
   2. Alpine will never push information into your pre-existing non-Alpine Mailchimp Merge Fields, e.g. “FNAME” or “LNAME”. This is to preserve any data you have within these platforms. However, when pulling information from Mailchimp, Alpine will access these fields
   3. The list of fields synced by Alpine into Mailchimp can be customized and is covered above under Setup
      1. These can include both Base Fields and Custom Fields
         1. Currently, Alpine does not support syncing Derived fields into Mailchimp
   4. You may use these Alpine fields in your Merge Field sections in your campaign templates, e.g. *|ALPINE_B0|* for Alpine [Base] Name, etc
   5. If you accidentally delete these Merge Fields within Mailchimp, they will be restored during the nightly sync from Alpine
   6. If you replace or set any values for these Alpine-managed Merge Fields within Mailchimp, they will be overridden/replaced on a nightly basis
   7. Two additional calculated fields will always be synced into Mailchimp on a nightly basis:
      1. Last Donation Amount (in full $0,000.00 format, including cents even if zero).
      2. Last Donation Date (in MM/DD/YY format, omitting leading zeros where appropriate, e.g. 5/2/19 instead of 05/02/19).
4. Push remaining Constituents from Step 2 with data from Mailchimp Merge Fields identified in Step 3 into Mailchimp.
   1. Each Constituent will be associated with an email address. Email addresses will be pulled from the [Base] Email field, as well as any Custom Fields that are of type Email. If multiple constituents share the same email address (either via Custom Fields, Base Fields, or a mix of the two), then the following priority will be used as which Constituent’s information will be used for that email address:
      1. Custom Fields
      2. Base Fields
      3. N.B. Do not rely on this pattern, we highly encourage you to maintain unique email addresses per Constituent within Alpine to minimize the chances of email address collision
   2. Mailchimp will automatically perform matching based on email for all passed-in email addresses from Alpine. If Alpine passes in an email address from a Constituent that does not have a corresponding contact within Mailchimp, a new contact within Mailchimp will be created with Subscription Status: Subscribed.
   3. Alpine will never override the pre-existing subscription status within Mailchimp if the matched Mailchimp Contact already exists. For example, if someone is unsubscribed within Mailchimp, Alpine will never reset that status
      1. However, if you delete contacts out of Mailchimp, Alpine will re-sync them into Mailchimp. To prevent this from happening, either leave them within Mailchimp marked as Archived (instead of deleting), as that will leave them in the system but Alpine will not override (as they already exist within Mailchimp)

After Alpine has synced its entire constituency base into Mailchimp, it will look at any Alpine Tags that have been set to sync on a nightly basis, and repeat the process described above, with the following differences. To configure an Alpine Tag to sync automatically on a nightly basis, please refer to the Setup section above.

• Instead of Step 1 (“Take every single Constituent within your Alpine database.”), it will only take Constituents that are tagged with the Tag in question
• After Step 4 (“Push Constituents into Mailchimp”), it will perform the additional step of creating a Mailchimp Tag (or finding one if it already exists) and associate the Constituents with that particular Mailchimp Tag
• First, Alpine will fetch a list of all Mailchimp Tags from Mailchimp (internally, within Mailchimp they are called Static Segments), selecting those that begin with “[Alpine: ”
• For example, a Mailchimp Tag titled “[Alpine: Created 1/20/20 1:45 PM ET] Test Tag 1”
• Within those matched Mailchimp Tags, look for one whose name matches the corresponding Alpine Tag
• For example, if the Alpine Tag name is “Test Tag 1”, then it will match the Mailchimp Tag “[Alpine: Created 1/20/20 1:45 PM ET] Test Tag 1”, or one named “[Alpine: Updated 1/24/20 2:39 PM ET]”.
• If no Mailchimp Tag exists that matches the Alpine Tag name, then a new Mailchimp Tag will be created with its name adhering to the following format:
• [Alpine: Created M/D/YY HH:MM AM TZ] TAG_NAME
• Now that a Mailchimp Tag exists (either created on the spot, or previously found), then the Constituents under the Alpine Tag will be associated with that Mailchimp Tag
• N.B. Similar to Step 4a above, all emails linked to the Constituent ([Base] Email, as well as any Custom Fields of type Email) will be associated with this Mailchimp Tag. This is regardless of if those columns are selected in the Alpine Constituent reporting interface.

Syncing Email Subscriber Activity

EMAILS SENT, OPENED, AND LINKS CLICKED

Alpine will now look at all Mailchimp Audiences configured within Setup (see above), both the Push as well as Pull audiences (if they are the same audience, then it will only sync unique audiences). For that given audience, Alpine will fetch a list of all Email Campaigns sent to that Audience in the two weeks proceeding the last time the email integration synchronization was run. If no date is present (e.g. the first time the integration runs), then it will pick the date of 12 months ago. As this email integration runs nightly, this will usually correspond to any email campaigns sent within the last two weeks.

For Automated Mailchimp Campaigns, Alpine will sync all component email campaigns within the larger Automated Email Campaign. For A/B Mailchimp Campaigns (known as Variate), Alpine will sync not only the A and B versions, but also the final winning email campaign sent to the rest of your Audience.

For each Mailchimp Campaign, Alpine will fetch campaign subscriber activity (email address recipients, email opens, links clicked) since the last time the synchronization was run, or if not present, twelve months ago. Therefore, there are three types of campaign subscriber activity:

Campaign Subscriber Activity Types
Email Sent	Email Opened	Email Link Clicked
Email Address	Email Address	Email Address
Email Body (HTML)	Email Body (HTML)	Email Body (HTML)
Email Subject Line	Email Subject Line	Email Subject Line
Timestamp	Timestamp	Timestamp
		URL of Link Clicked

Campaign subscriber activity will be skipped if the given email address from Mailchimp matches one of the values under Setup (Ignored Email Addresses (Comma Separated)).

If during this campaign subscriber activity sync, if a new email address is found (e.g. not previously present in the database), then a new Alpine Constituent will be created with the name “Contact for email@address.com”. This may occur if you have deleted a contact out of Mailchimp, but that contact had received an email communication at some point in the past.

If multiple Constituents match a given Email Address, then all matched Constituents will have Actions created under their own profiles. For example, if the email address “hello@example.com “ is linked to three Constituents (two with the “[Base] Email” field set to “hello@example.com”, and a third with a Custom Field of type Email called “Secondary Email” set to “hello@example.com”), then three email open Actions will be created (and associated with the three Constituents).

Syncing Email Campaign Content

HTML BODY + SUBJECT LINE + PREVIEW TEXT

For all Mailchimp Campaigns tracked with all Alpine Actions related to email subscriber activity (emails sent, emails opened, email links clicked), Alpine will sync the content of the Mailchimp email campaign into its own database (accessible via “View Preview”). Alpine will attempt to download the following information per Mailchimp email campaign:

• HTML Content (images, CSS, as displayed to end-users)
• For A/B email campaigns (internally referred to as Variate), the A version will be recorded
• Plain Text Content (not always available, depending on your Mailchimp plain-text campaign generation settings)
• For A/B email campaigns (internally referred to as Variate), the A version will be recorded
• Subject Line
• Preview Text

If you have any questions about the Mailchimp/Alpine integration be sure to reach out to your Customer Success Manager/Support Team.