Jethro Mailchimp Integration

Churches sometimes need to send bulk email, such as newsletters, to their members. Jethro cannot send bulk email directly. Bulk emailing is a difficult job, requiring handling unsubscriptions and bounces, optimizing deliverability and so forth. Rather, Jethro offers integration with Mailchimp, a well-known bulk email provider with a generous free tier.

Specifically, once configured as described on this page, Jethro provides:

  • a background service which will synchronize names and email addresses from a Jethro to Mailchimp. You can have multiple sets of recipients, e.g. one for each congregation plus one for a church-wide newsletter, each synced to Mailchimp. This allows Jethro to be your source of truth for contact details and email recipients, with Mailchimp kept in sync.
  • an interface that lets you compose a HTML email to send to multiple users via Mailchimp:

    (Mailchimp has a more feature-rich interface for composing bulk emails which you can use too)

Mailchimp adds an unsubscribe link to outgoing emails. If someone clicks the unsubscribe link, Mailchimp flags them as 'Unsubscribed', and although Jethro-to-Mailchimp synchronizations for that person still occur, the 'unsubscribed' status is remembered and Mailchimp will not send them further emails.

Configuration

The configuration process is as follows.

1. Create an API Key

Jethro will be updating Mailchimp, and needs a means of authenticating.

In MailChimp, go to the Mailchimp API Keys page (logging in if necessary). This can also be done by clicking on your username, then Account & Billing, clicking the Extras drop-down and clicking API keys:

In the Your API Keys section, click Create A Key to generate a key. Call the key 'Jethro' (although the name doesn't matter).

Your new API key will display:

Click Copy to Clipboard.

Switch temporarily to Jethro, go to Admin -> System Configuration, find the Mailchimp Sync section and paste in the key:

Now return to Mailchimp and click Done to dismiss the New API Key screen. You will be left on the API Keys screen, with your new key listed.

2. Create a Jethro report

In Jethro, create a report (Under 'Persons') that returns the set of users you wish to receive a particular bulk email (e.g. our newsletter).

If this is a specific subset of people, create a Group for people to be emailed, and then have the report return the group's members. In this example we have a report called 'Coast Card', that are members of Jethro group 'Coast Card':

Save the report, and ensure it returns the correct set of people you would like to be emailed through Mailchimp. Keep a browser tab with this report open, as we will need to return to it soon.

3. Create a Mailchimp Audience

Mailchimp calls a set of users (recipients of one email type, e.g. a newsletter) an 'Audience'. Go to the Mailchimp Audiences section and create a new Audience if you haven't yet done so. In this example the newsletter (and audience) is called 'Coast Card':

On the right, click Manage Audience, then Settings:

Click Edit merge fields/tags:

Click Add A Field and define new fields as in this screenshot:

Click Save Changes.

4. Link Jethro Report to Mailchimp Audience

Return to the Mailchimp Audience settings:

Copy the Audience ID (1fab01b311 in this example).

Return to Jethro and locate the person report created above, and reconfigure it (click 'Configure').

At the bottom of the report's configuration, fill in Mailchimp List ID with the Audience ID from the Mailchimp audience:

You will only see Mailchimp List ID part if you are a full Jethro admin. If you aren't, please email us the Audience ID (along with the API key), and let us know the report ID, and we'll configure it.

Once a report has a Mailchimp List ID, you will notice a new Send campaign link:

This allows you to send an email through Mailchimp:

Everything is now configured.

5. Wait for synchronization

Easy Jethro's Mailchimp synchronizer is a background process with no visible UI in Jethro. The synchronizer runs every hour on the hour. When it next runs, the synchronizer will notice that your instance has a Mailchimp API key, and that one report has a Mailchimp List ID associating it with a Mailchimp audience, and will synchronize report persons to Mailchimp.

After the next hour begins, visit your Mailchimp Audience Contacts page to view the imported contacts:

The synchronizer also writes a log file, visible under Documents, which you can inspect for errors:

(A note for self-hosting Jethro users (i.e. not using hosted Easy Jethro): you will need to set up a cron job or systemd timer to periodically invoke php $JETHRO_INSTALLATION_DIR/scrip|ts/mailchimp_sync.php)

Summary

In summary, we have:

  • Created an API key so that Mailchimp will trust Jethro when it connects to synchronize
  • Created a Mailchimp 'audience', a set of recipients of a particular type of email (a newsletter).
  • Created a Jethro report, whose persons get synchronized with a particular Mailchimp audience.

You may create as many Jethro reports with linked Mailchimp audiences as you like, and each will be synchronized.