Set up newsletter tool

Overview

beabee is able to link the database with your newsletter tool. Currently we only have the option to synchronise beabee with Mailchimp.

Mailchimp data is synced both ways to and from beabee. This allows community organisers to have all their contacts in one place (on beabee), while still leveraging the newsletter functionality of Mailchimp.

Limitations

beabee can currently only sync with one Mailchimp audience, see merging multiple audiences for details.

Setup

We need to create an API key and a webhook in Mailchimp. You will receive a URL with a secret token from the beabee team. Important: The URL should not be passed on to third parties.

Once you have received everything, go to https://community.beabee.io/callouts/mailchimp-setup. Via this callout you can send us all the Mailchimp details we need from you at the end. Once you have opened the callout, log into your Mailchimp account in another tab.

1. Login to Mailchimp and go to your Account page.

2. Go to Extras -> API keys

3. Create a key

4. Copy the API key and paste it into the callout. This key should be kept secret, anyone who has it could access your Mailchimp account.

5. Set the API key label to "beabee - live"

6. Now go to your audience settings to add the webhook

7. Copy the unique audience ID and paste it into the callout, then go to Webhooks.

8. Create a webhook

9. Enter the URL the beabee team provided into the callback URL field and ensure the rest of the settings reflect the screenshot below

10. Done! Now submit the callout and wait for the beabee team to do the rest.

Data model

The following data is synced, grouped here by how it is stored in Mailchimp

Email address

The contact's email address

Subscription status

• Subscribed: Can be emailed

• Pending: Has been sent an email asking them to confirm they want to be subscribed

• Unsubscribed: Can't be emailed but does still count towards billing

• Archived: Can't be emailed and no longer counts towards billing but data has not been deleted, if the user is unarchived their data would be restored (e.g. open/click rates)

• Deleted: Data is fully deleted from Mailchimp, if the user is re-added they will have no previous data associated with them

Tags

Contacts can have one or more tags.

beabee currently has one standard tag, "Active member" which is set on contacts who have an active "member" role. Community organisers can also assign a tag to a segment and this will be set on all contacts who are in the segment.

Merge fields

Contacts can have merge fields (custom fields), currently we use:

Note: This currently isn't editable by community organisers

Merging multiple audiences

beabee can only sync with one Mailchimp audience at a time. This is how Mailchimp recommend you organise your contacts, but it is common for community organisers to use separate audiences. If you want to get the most out of beabee and Mailchimp, you should merge these audiences together.

For the purposes of this guide, we will refer to the primary audience as the audience you are keeping, and the secondary audience(s) as the one(s) you will merge into the primary audience.

Before starting this process you should read the following Mailchimp guides:

• Best practices for audience management

• Creating audience groups

• Combining audiences - note this process does not use the combine audiences tool, but the caveats are the same

In particular you should note:

• You will lose some Mailchimp metadata for your secondary audiences, including their engagement score, tags and open/click rates for newsletters.

• You will need to change how you send newsletters in Mailchimp once the process is complete

The process

Step 1: Create an audience group in your primary audience

1. Go to audience groups

1. Create an audience group for newsletter subscriptions

1. Put current audience in relevant newsletter groups

1. Configure these audience groups in beabee. You can configure the following options:

• newsletter-groups: a JSON list of groups that can be displayed to the user on signup

• newsletter-default-status: the default status when a user signs up (e.g. subscribed) Use these to create different scenarios in the join flow (provided newsletter opt-in is enabled).

Step 2: update embedded newsletter signup forms (and other newsletter signup processes)

If you have any embedded signup forms on your website you will need to update them to either let users choose which groups they want to join, or you can choose to automatically opt them in.

This guide shows you how: https://mailchimp.com/help/automatically-add-subscribers-to-a-group-at-signup/

If you have any other custom integrations that handle newsletter subscription, you will also need to update these if you want new contacts to automatically join certain groups (or be given the option to).

Step 3: merge the secondary audience

Mailchimp's combine audience tool can only be used if your audience hasn't been used in at least 7 days. This probably will never be the case! Instead we can use beabee to merge the audiences together.

This involves configuring beabee to point to your secondary audience, running a newsletter sync job, then pointing beabee at the primary audience and running another sync job.

Please be aware of the following:

• A contact has one subscription status in beabee, but can have different ones in each audience of Mailchimp. If so, the status in the primary audience will almost always win. This is especially true if the contact is unsubscribed as Mailchimp doesn't let you resubscribe someone without their permission.

• You could create a new audience and merge all your audiences into that. This gets around the problem as Mailchimp no longer remembers that the audience member was unsubscribed. This is only legitimate if you definitely have the contact's permission, you shouldn't use this to resubscribe people who have asked not to be contacted

So the steps are:

1. Set BEABEE_NEWSLETTER_LISTID to the secondary audience ID

2. Run a resync, you should untick "Also update the data on the newsletter provider" as we will be discarding this audience. You can choose if you want to trust beabee's subscription status or Mailchimp's one. This subscription status will be used in the resync to the primary audience for new contacts.

3. Set BEABEE_NEWSLETTER_LISTID to the primary audience ID

4. Run a resync again. Note if you use beabee as the trusted source for subscription statuses then you might get sync errors if Mailchimp refuses to change a contact's subscription status (typically if they have previously unsubscribed)

5. Run the resync again, at least in dry run mode. You should see that no changes are required

Step 4: update your Mailchimp workflows

You should create segments which reflect all the workflows you were previously using with different audiences. As a minimum, this probably means at least creating a segment for active members (now identified with an "Active member" tag).

You will also need to adjust any automations you might have, to ensure they are triggered correctly.

Syncing

From Mailchimp to beabee

On events from Mailchimp:

beabee uses a webhook to get updates from Mailchimp, it listens for the following events:

• Subscribe -> A new contact has been added to Mailchimp, create the contact in beabee

• Change email -> A contact's email address has changed, update it in beabee

• Update profile -> A contact's profile data has changed, update it in beabee

• Note: We currently only support updating the contact's first name and last name, all other updates are ignored

From beabee to Mailchimp

Immediately when an action is triggered in beabee

• A new contact is created -> Create the contact in Mailchimp

• A contact is updated (e.g. update address, contribution, etc.) -> Update the contact's merge fields in Mailchimp

• A contact's membership role becomes active -> Add the "Active member" tag

• A contact's membership role becomes inactive -> Remove the "Active member" tag, set their status to unsubscribed

• A contact answers a call out that has been assigned a newsletter merge field -> Update the contact's merge field with their answer to the call out

• Resync is triggered -> All contacts are reuploaded to Mailchimp, overwriting all merge fields and creating any unknown contacts in an unsubscribed state. Contacts that are only in Mailchimp are imported into beabee Note: We don't currently sync tags

Daily jobs

• Archive members that have expired in the last day -> Remove the "Active member" tag, set their status to archived

• Update members who have joined a segment in the last day -> Add segment tag to contact in Mailchimp

• Update members who have left a segment in the last day -> Remove segment tag from contact in Mailchimp

Problems

• If a contact manually unsubscribes from Mailchimp they can't be opted back in via the API at a later date