eWay-CRM Integration with Mailchimp

Integration of Mailchimp with eWay-CRM is used for automatic synchronization of contacts and selected marketing data.

Content

• What the integration is used for
• What data is synchronized
  
  • Custom fields
• What to prepare before launch
  
  • API key
  • Audience ID
  • HASH
  • Synchronization of custom fields
• Configuration file
• Initial pairing of existing contacts
• How synchronization works in operation
• Limitations and recommendations

What the integration is used for

The integration is designed so that new or modified contacts from eWay-CRM are transferred to the appropriate contact list (audience) in Mailchimp, including standard contact data, selected custom fields and categories (referred to as tags in Mailchimp).

What data is synchronized

A contact can only be created in Mailchimp at the moment when it has an email filled in and a target audience selected.

In the default scope, the email address, first name, last name, phone and address are transferred to Mailchimp. When creating an audience, Mailchimp has standard merge fields FNAME, LNAME, ADDRESS and PHONE prepared; additional data can be added as custom fields. A typical part of mapping is also company name, date of birth, newsletter subscription status and contact category. Merge fields in Mailchimp are used for storing custom data about a contact and can subsequently be used for personalization and segmentation.

Fields in eWay-CRM	Fields in Mailchimp	Note
Email	email_address	Required field and identifier of the contact
Name	FNAME	Standard merge field
Last Name	LNAME	Standard merge field
Telefon	PHONE	Standard merge field
Company address	ADDRESS	In Mailchimp it is one structured field
Company	COMPANY	A corresponding merge field must exist
Date of birth	BIRTHDAY	Optional, date format
Do not send newsletter	status	Typically subscribed / unsubscribed
Categories	tags	Used for labeling and segmentation

Custom fields

For custom fields, it is necessary to watch data types. Mailchimp supports, for example, text, numeric fields (number), selection field (radio), list (dropdown), date (date), birthday (birthday), address (address), ZIP (zip), phone (phone), url and imageurl.

Field specifics are:

• in radio and dropdown fields, values in eWay-CRM must correspond to values in Mailchimp
• for date, Mailchimp validates specific formats
• for birthday, it expects format MM/DD
• when synchronizing address via a custom field, it is possible to assemble it from multiple custom fields, which Mailchimp combines into one field

What to prepare before launch

Before the first launch, we recommend exporting contacts from Mailchimp and saving a backup.

For the integration to work, prepare a Mailchimp API key and Audience ID for each audience you want to use. The API key has full access to the account, therefore store it as carefully as a password.

In eWay-CRM, prepare an API user – see article How to Create API user.

API key

You generate the API key at the moment when you click on your user icon in the top right corner of the Mailchimp account, select Profile and then choose Extras and API keys.

Here, using the Create a Key option, create a new key which you will use for setting the configuration file of the Mailchimp application in eWay-CRM. Copy this key.

Subsequently, it is necessary to insert it into the configuration of the Mailchimp application – see below.

Audience ID

The second necessary value is Audience ID, which determines to which audience the contact belongs – in Mailchimp it is possible to have multiple audiences.

Here it is necessary to go to the Audience tab, click on the three dots above the contact list and select the option Audience settings.

 

Here it is enough to copy the value in the Audience ID field.

This value must be entered into the configuration file of the Mailchimp application (see below), but at the same time it is necessary to create a custom field in the Contacts module in eWay-CRM. It must be a field of type Drop Down, whose name is optional, but the value/values in the list must have the same value as the Audience ID you copied. If you want the field to be filled automatically when creating a contact, it is appropriate to set the list item as default.

HASH

In addition to the field for Audience ID, it is also necessary to create a field for HASH, where a value will be stored that uniquely identifies the contact against the contact in Mailchimp and there will be no creation of duplicates, as well as it will be possible to synchronize changes to the contact into Mailchimp.

This field must meet the following:

• it is created in the Contacts module
• its type is Link
• field name is optional

Synchronization of custom fields

If you want to synchronize additional custom data, make sure that corresponding fields exist in the respective audience. That means:

• I have created a field of a certain type in eWay-CRM
• I have created a field of the same or supported type in Mailchimp

When creating a field in Mailchimp, a so-called Merge Tag is entered, which identifies the field for API communication. The Merge Tag is entered in the Default merge tag value field (in this case it would be GROUPTEXT).

Each such connection must be set in the configuration file – see below.

Configuration file

The Mailchimp Connector application, which enables synchronization of contacts between eWay-CRM and Mailchimp, contains a file which needs to be set before the first launch. The data in the configuration file looks like this – explanations are provided:

<mailchimpConnector>
    <mailchimpConfig
        apiKey="API KEY" /> - API key which you copied from Mailchimp
    <crmConnection
        url="ADDRESS OF YOUR eWay-CRM WEB SERVICE"        - format with https://
        userName="USERNAME OF API USER"                   - username displayed in the Administration Center for your API user
        password="" />                                    - left empty if you did not set a password yourself
    <fields>
        <contactModule
            mailchimpAudienceFieldName="af_XX"            - database name of the field created in eWay-CRM - see Audience ID
            mailchimpSubscriberHashField="af_XY"          - database name of the field created in eWay-CRM - see HASH
            birthdayFieldName="af_XZ">                    - optional field if you want to copy birthdays (must be a Date type field in eWay-CRM)

            <customFields>
                <field customFieldName="af_XA" mailchimpMergeFieldTag="TEXTMF" />    - first, enter the database field name in eWay-CRM, followed by the Merge Tag that you defined when creating the field in Mailchimp
                <field customFieldName="af_XB" mailchimpMergeFieldTag="NUMBERMF" />  - add as many entries as the number of custom fields you want to synchronize
            </customFields>
        </contactModule>
    </fields>
</mailchimpConnector>

Based on this configuration, individual triggers that are part of the application are also set.

Initial pairing of existing contacts

After deploying the integration, it is appropriate to pair existing contacts in eWay-CRM with their counterparts in Mailchimp based on email address. The purpose of this task is to fill subscriber hash and the link to the audience so that further changes already run automatically. Mailchimp uses as a contact identifier an MD5 hash from the email address converted to lowercase, so email is decisive for the initial pairing.

It makes sense to run the initial pairing only at the moment when audiences, field mapping and contact import on both sides are completed. If you have a contact only in Mailchimp and it does not exist in eWay-CRM at all, it is necessary to first get it into eWay-CRM and only then pair it. After completing the initial pairing, further changes run automatically based on triggers.

How synchronization works in operation

During operation, the following changes are synchronized:

Synchronization from eWay-CRM to Mailchimp:

• creation of a contact
• editing of a contact, with only performed changes on synchronized fields being transferred
• unsubscribe or deletion of a contact

When a contact is removed in eWay-CRM, the contact is removed from the respective audience. It is good to know that Mailchimp distinguishes unsubscribe, archiving of a member and permanent deletion:

• unsubscribe in eWay-CRM unsubscribes the contact in Mailchimp
• unsubscribe in eWay-CRM unsubscribes the contact in Mailchimp
• deletion of a contact in eWay-CRM permanently deletes the contact in Mailchimp
• removal of audience in eWay-CRM leads to archiving of the contact in Mailchimp

Synchronization from Mailchimp to eWay-CRM:

• unsubscribe of a contact is synchronized

Limitations and recommendations

The most important limitation is related to how Mailchimp identifies a contact. Because the API uses an MD5 hash from the email address as the canonical identifier of a member, it is not suitable to synchronize multiple different contacts with the same email address into the same audience. In practice, a simple rule applies: one email address should correspond to one contact in one audience.

If you do not need separate audiences for business or legal reasons, consider a simpler model with one main audience and segmentation via tags and segments. Mailchimp recommends this approach. However, if you really need multiple audiences, the integration supports it via the field for audience selection in eWay-CRM.

For extending synchronization with additional custom fields, two practical recommendations apply. First, always verify compatibility of data types on both sides, especially for lists, dates, URLs and addresses. Second, take into account that the address in Mailchimp is one structured field, while in eWay-CRM it is usually divided into multiple separate items, so its mapping requires special configuration.