# 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](#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. \ The beabee team has shared an onboarding checklist with you in Google Drive. In the section **Onboarding > Connect Newsletter Tool**, you'll find a table. At the end of the process, enter all relevant information there so that the beabee team can access it at any time. First, open the shared Google document. Then, log into your Mailchimp account in a separate 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 send it to the beabee team. **This key should be kept secret**, anyone who has it could access your Mailchimp account. For this reason, do not use a Google Doc to share the key. Instead, use [**Onetime Secret**](https://onetimesecret.com/) to transmit the information securely. There, you can generate a secure link containing the key, which you can then send to the beabee team via email. The link can only be opened once.

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 table, 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 CrowdNewsroom 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: | 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 ## Merging multiple audiences beabee can only sync with one Mailchimp audience at a time. This is how Mailchimp [recommend you organise your contacts](https://mailchimp.com/resources/one-audience-organize-contacts-to-optimize-marketing/), 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](https://mailchimp.com/help/requirements-best-practices-audiences/) * [Creating audience groups](https://mailchimp.com/help/create-new-audience-group/) * [Combining audiences](https://mailchimp.com/help/use-combine-audiences-tool/) - 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 {% hint style="info" %} We assume you want to combine two audiences for this guide, but you could repeat the process multiple times to combine more audiences. {% endhint %} #### **Step 1: Create an audience group in your primary audience** 1. Go to audience groups

2. Create an audience group for newsletter subscriptions

3. Put current audience in relevant newsletter groups

4. 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).

Scenario	`groups`	`default-status`
Automatically subscribe to audience, no newsletter opt-in is shown as there are no group options	empty	subscribed
User will be given a simple opt-in tick box to be subscribed, no group options	empty	empty
Automatically subscribed, then user is shown a list of groups to join	List of groups	subscribed
User shown list of groups, they are only subscribed to the audience if they select one or more	List of groups	empty

#### **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: 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](https://mailchimp.com/developer/marketing/guides/sync-audience-data-webhooks/) 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://wiki.beabee.io/help-center-english/onboarding-guide/set-up-newsletter-tool.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.