Knowledge Base

Browse our knowledge base articles to quickly solve your issue.

Configuring Workbooks and MailChimp

NOTE: Video shows the old version of Mailchimp User interface, but the screenshots on this page reflect the most recent version of Mailchimp UI. 

Before starting your integration with MailChimp please make sure that you meet the prerequisites detailed on the previous page.

Setting up a list within MailChimp

All contacts from Workbooks are synchronised into a single MailChimp list. This list is then segmented into different groups which correspond to the originating Workbooks Marketing Campaigns (using the Campaign's Public Name). So, before setting up the integration, make sure you've created a list within MailChimp so that any data from Workbooks has somewhere to go.

NOTE: MailChimp limits the number of groups on a list to a maximum of 60.

To create your list, first, you will need to log in to MailChimp and select Create a List.


Creating a MailChimp API Key

In order for Workbooks to access your MailChimp account, you need to create a MailChimp API key. Within MailChimp click Account and choose API Keys & Authorized Apps.


Click to enlarge

Setting up your Workbooks/MailChimp Integration

Navigate to Start Configuration Email & Integration MailChimp Config. Enter the MailChimp API key that you created above. (If you haven't created it already you can click on the link provided (above the MailChimp API Key field). Make sure you paste in the key exactly as it appears in MailChimp. Click Save.

You now need to enter your MailChimp List name. As long as you set this up before beginning your integration, you'll find this by using the drop-down menu.

The MailChimp Grouping Name field will default to 'Subscriptions', which you can leave as it is and click Save. (MailChimp requires that the groups on the list are grouped together, ie, groups of groups. 'Subscriptions' is the group in which the Workbooks groups will be held.)

MailChimp Attribute Mappings

As well as synchronising names and emails addresses between MailChimp and Workbooks you can also synchronise other fields between the two systems. This is controlled used the Attribute Mapping table.

You can control which fields in Workbooks are available for use within emails generated in MailChimp so that the values from those fields are pulled through into the email when a placeholder (Merge Tag Name) is used in MailChimp. (This only applies to fields on Leads and People records.)

When you've saved the MailChimp settings described above, a tab called MailChimp Attribute Mappings will appear. In this tab, you'll see that the most commonly used mappings have already been set up for you. To create more mappings (which can be for standard or custom fields), click Add.

See the dropdown picklist next to Workbooks Field Name to choose the appropriate option. Notice that if a field is only available for either a Person record or a Sales Lead record this is shown in brackets after the field name. Fields that are common to both Sales Leads and People are not followed by anything in brackets.

When you choose a field name, the MailChimp Merge Tag Name fields will auto-populate with an abridged version of the Workbooks Field Name. These options will be available to you in MailChimp when you insert Merge Tags into a campaign email. You can change the Merge Tag name if you want but make sure that you only use unique values.

NOTE: MailChimp limits the number of merge fields on a List to a maximum of 30. Adding more than this will result in the user seeing a MailChimp error message. In addition, MailChimp list fields are limited to 255 characters. If you map a Workbooks field that is larger than this, the data will be truncated in MailChimp.

Configuring MailChimp Settings Using Workbooks

To be able to control the integration of a Workbooks Marketing Campaign with MailChimp, the Campaign record must first be created in Workbooks. Click here for information on how to create a Campaign.

Now you can use the Marketing Campaign MailChimp Integration Wizard to guide you through associating your Workbooks Campaign with MailChimp. The Wizard can be found by opening your Campaign and clicking the Configure MailChimp Integration button.

There are two types of integration you can choose from:

  • MailChimp Campaign
  • MailChimp List only

MailChimp Campaign 
Choose this option if you want to track opens, clicks and bounces generated by your Campaign and synchronise this information back into Workbooks. An example of this would be if you wanted your salespeople to follow up with any Campaign members who have opened a particular email or clicked on specific content.

MailChimp List only 
Choose this option if you don't require the MailChimp summary information to be synchronised back into Workbooks. For example, it would make sense to use this option if you are sending a monthly newsletter as you would only have to maintain one Campaign within Workbooks and can send several emails from MailChimp to the relevant group on your MailChimp list.

As you click through the Wizard you can select your precise requirements such as specifying a type for your MailChimp campaign (A/B Split, Plain Text, etc), as well as specifying the Subject, Sender Name and Reply To email address for the MailChimp email.

If your Reply To email address is different to the email address you use to login to MailChimp, you will need to verify the domain name within MailChimp. 

Mailchimp info

Once you have added the email address you will be sent a verification email with a link for you to open.

Upon completion of the Wizard, a MailChimp campaign will have been created and associated with your Workbooks Marketing Campaign. The final step of the Wizard includes a hyperlink to the MailChimp campaign so you can open it and tailor it.

Synchronising Workbooks Campaign Members into MailChimp

When you've completed the MailChimp Synchronisation Wizard, the Workbooks Campaign is automatically synchronised to MailChimp using a process that runs periodically:

_Sync to the mailchimp list 

  • Adds Workbooks Campaign Members to the MailChimp list
  • Updates members of MailChimp List when Workbooks People/Leads are updated (matches based on email address)
  • Sends unsubscribes to MailChimp when Workbooks People/Lead opt out of email ('No Email' is set to true)
  • Opts Workbooks People/Leads out of email when they unsubscribe in MailChimp

Once the process has run, you will see a new Group within the MailChimp List, with a name that corresponds to the Public Name of your Workbooks Campaign. If you selected to integrate 'MailChimp Campaign' rather than 'MailChimp List', you will also see a Campaign created in MailChimp. 

The script runs at regular intervals to accommodate any additional changes made to the Campaign since it was last synchronised with MailChimp and these intervals can be specified to meet your requirements.

To view or change the interval click Start Configuration Automation Processes and select the process on the right called '_Sync to the mailchimp list'. By default, the process runs every hour, however using the dropdown picklist next to Schedule you can change the frequency with which the script runs. The screenshot below shows the Process Record and some important information relating to the scheduling of the Process. Also, make sure that the Process has been enabled and that it is set to Run As the 'Automation' User.

Click to enlarge

If you've made changes to your Workbooks Campaign and don't want to wait for the next scheduled run, you can run the script at any time by clicking Run Now. You can also use the 'Re-synchronise' option on the Workbooks Marketing Campaign, but this only forces the process to 'Run Now', it does not remove anything from MailChimp nor  does it 'reintegrate' the Campaign.
When this process has completed you'll see within MailChimp that your MailChimp Campaign and/or Group have been updated accordingly.

If you add members to your Campaign, these changes won't be reflected in MailChimp until the script has run and the next synchronisation has taken place.

If you remove members from your Campaign, these members will not automatically be removed from the MailChimp Group. To remove members, you must manually remove them from both the Workbooks Campaign and the MailChimp Group.

Campaigns in a Closed state will not be synchronised with MailChimp. This is particularly useful if you've previously synchronised a Campaign with Workbooks and want to remove the synchronisation without losing any synchronisation data.

MailChimp lists allow you specify which fields are mandatory. If you want to create new or update existing subscribers in MailChimp, the equivalent Workbooks fields must be populated and must be included in the Attribute Mappings.

NOTE: If you make a field mandatory within MailChimp, synchronise the Campaign Members from Workbooks to MailChimp and the Person Record within Workbooks contains a blank value for this field, then MailChimp will reject this Person and they won't appear within their intended group.

This is a common cause for People not successfully synchronising Campaign Members from Workbooks to MailChimp and is something to look out for.

Finalising MailChimp Campaign and Sending to Members

Now that synchronisation has taken place and MailChimp contains the Workbooks Campaign information, you can use the MailChimp Campaign Builder to send your Campaign. To get to the MailChimp Campaign Builder screen open the MailChimp reveal within your Workbooks Campaign and use the hyperlink you see there.

Using the wizard you can ensure that you have selected the correct recipients, subject line, reply email address, tracking preferences and the style/design of the email which you send out. Following the wizard will ensure that you have completed all the necessary steps to send out your email.

Before sending out your email it's worth looking at some of the steps within the wizard. As the content of your email is important, MailChimp offers a variety of basic and designer templates. Many of these can be customised to meet your specific requirements.

You can select the designs which you think are most appropriate for your audience. You can also import your own templates if you have some already created (Select Import Template from the template type pick list).

An example of this would be to import an email template that you use within Workbooks. Alternatively, you can create your own templates provided you have the necessary skills to do so (templates are written using HTML & CSS).

You will also be asked to verify the email address which you intend to send the Campaign from. This is a standard process within MailChimp to ensure that people do not spam on behalf of others.

NOTE: MailChimp also provides you with templates which are specifically designed to be read using mobile devices. This is a small extra which can make a big difference to those who read emails on mobile devices.

Once you've completed the wizard click Confirm > Send Campaign.

Reporting within MailChimp

Within MailChimp, you can view the summary of the Campaign. This can be done by going to Reports > Your Campaign Name. This gives you get an overview of emails that have been opened, unopened and any clicks.

The information is presented in both a graphical and text form. Along the top of the page, MailChimp also gives you the option to download the summary, print the summary or share with others.

Synchronising the MailChimp Results into Workbooks

The results from MailChimp can be pulled back into a Statistics tab in Workbooks to give you an overview of your Marketing Campaign on one platform. For this to take place a process is required to run which processes this information from MailChimp into Workbooks:

_Sync mailchimp campaigns

  • Updates the Campaign Members of open integrated Marketing Campaigns with email activity - email opens, clicks, hard bounces, soft bounces

As with the previous process, it is set to run every hour by default, however, the frequency with which it runs can be changed to meet your requirements. To view or change the interval click Start Configuration Automation Processes and select the process on the right called '_Sync mailchimp campaigns'.

You also have the option to run the script manually at any time by clicking Run Now. This will synchronise any MailChimp activity to the corresponding Workbooks Campaigns.

Please check this process has been enabled and is set to Run As the 'Automation' User. 

NOTE: The information pulled back into Workbooks will only be updated for 30 days. After this, the information will remain as it is indefinitely.

View Workbooks Campaign Summary

When the synchronisation script has run you can view the MailChimp summary within the Workbooks Campaign Record. To do this open the relevant Workbooks Marketing Campaign. Opening the Member Email Summary reveal gives an overview including information such as the total number of members with email addresses, those who have unsubscribed, opted out and those who are eligible for email.

If you open the Statistics tab, you'll see a high-level summary of your Campaign. You'll also see information such as the total number of emails sent, the percentage of opt-outs, the number of opens and the number of clicks.

It's also possible to see the summary for each individual target by opening the Members tab. When first opened, the view shows basic information about the member. However, you can configure the grid to display columns showing details such as Email Opens, Email Clicks, Emails Soft Bounced and so on.

For even more detailed information open an individual Member's record and open the MailChimp Activity tab. Here you'll see real-time information on all related MailChimp activity for that Campaign Member, including details of what content they clicked on