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.

Merging multiple audiences

beabee can only sync with one Mailchimp audience. This is how Mailchimp recommend you organise your contacts but it seems pretty common that organisers instead use different audiences for different newsletters. To fully integrate Mailchimp with beabee you therefore need to merge your audiences and use groups for the different newsletters instead.

Things to note

• You will lose your contact engagement score and open/click rates, these will reestablish over time.

• Mailchimp charges per contact per audience, therefore by merging your audiences you could save money.

• ...

Process coming soon

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:

beabee field	Mailchimp merge field	Example
First name	FNAME	Will
Last name	LNAME	Franklin
Contribution monthly amount	C_MNTHAMT	5
Contribution period	C_PERIOD	annually
Contribution description	C_DESC	£60/annually
Referral code	REFCODE	WF301
Polls code	POLLSCODE	WF678

Note: This currently isn't editable by community organisers

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