Discourse Newsletter Integration Plugin

[Osama]

	Summary	Discourse Newsletter Integration adds customizable newsletter subscription services to your instance.
	Repository Link	https://github.com/discourse/discourse-newsletter-integration
	Install Guide	How to install plugins in Discourse

As this is an official plugin maintained by the Discourse team, support, bug, ux, and feature requests can be made in the respective categories here on Meta, and tagged with the appropriate plugin tag. Click on a link below to get one started.

 Support  Bug  UX  Feature

Features

• Admins can configure a global newsletter that will be synced with a mailing list in the newsletter provider.
• Users are able to subscribe to the newsletter from a site banner
  • Once the banner is dismissed, it won’t appear again for the user.
• A checkbox is added to the user preferences page (/my/preferences/emails), allowing users to change their newsletter subscription at any time.
• Subscribers are added or removed from the linked mailing list in the newsletter provider via their API when users subscribe or unsubscribe.
• The plugin syncs the subscription status between Discourse and the newsletter provider.
• Currently, the plugin supports Mailchimp as the newsletter provider and only one global newsletter for all users. Support for additional providers and newsletters limited to groups is planned for future releases.

Configuration Guide

To enable the plugin, you can use the toggle on your /admin/plugins page, or by checking the discourse newsletter integration enabled admin setting. You can also access the plugin’s settings from this page too:

Customize text in Banner and User Settings

Users will see a banner about the newsletter, allowing them to subscribe or dismiss it. This banner can be customized to suit your forum’s needs better, and will only be visible if all settings related to the plugin are configured. Once dismissed, the user will not see it again but can choose to subscribe from their preferences page.

You can customize the subscribe banner text from the admin panel. Here are the customizable labels for the banner:

• js.discourse_newsletter_integration.banner.heading
• js.discourse_newsletter_integration.banner.description
• js.discourse_newsletter_integration.banner.subscribe

• js.discourse_newsletter_integration.banner.manage_preferences
• js.discourse_newsletter_integration.banner.thank_you
• js.discourse_newsletter_integration.banner.added_to_newsletter

You can also customize the name of your newsletter on what each user sees in their preferences page:

• js.discourse_newsletter_integration.preferences.section_head
• js.discourse_newsletter_integration.preferences.checkbox_description

Mailchimp Integration

There are three Discourse site settings related to the Mailchimp integration:

Name	Description
discourse newsletter integration mailchimp api key	API key for your Mailchimp account.
discourse newsletter integration mailchimp list id	The ID of your Mailchimp Audience that you want to sync with Discourse.
discourse newsletter integration mailchimp server prefix	The subdomain part of the URL that you see when you log into your Mailchimp account, e.g. us14 and us19.

discourse newsletter integration mailchimp api key

To generate an API key, follow these steps:

1. Navigate to the API Keys section of your account.
2. Click Create New Key.
3. Name your key.
4. Click Generate Key.
5. Click Copy Key to Clipboard. Save your key someplace secure.
6. Click Done.

About API Keys | Mailchimp

discourse newsletter integration mailchimp list id

Each Mailchimp audience has a unique audience ID (sometimes called a list ID) that integrations, plugins, and widgets may require to connect and transfer subscriber data. The audience ID is generated by Mailchimp’s system when the audience is created and cannot be changed.

To find your audience ID, follow these steps:

1. Navigate to Audience
2. Select the Audience you want
3. Click the Settings drop-down and choose Audience name and defaults.
4. In the Audience ID section, you’ll see a string of letters and numbers. This is your audience ID.

Find Your Audience ID | Mailchimp

discourse newsletter integration mailchimp server prefix

Log into your Mailchimp account and look at the URL in your browser. You’ll see something like https://us19.admin.mailchimp.com/; the us19 part is the server prefix. Note that your specific value may be different.

Known issues

This plugin has basic functionality and works well, but here are some known issues we will be handling in the future:

Changing Mailchimp accounts

After setting up the Mailchimp integration and establishing audiences for a newsletter, if you change to a new account (via site settings), audiences won’t be synced with the new account.

Hosted by us? This plugin is available on our Enterprise plan.

[Jagster (Jakke Lehtonen)]

Does it work without Mailchimp or is it kind of frontend for services of Mailchimp (as quite typically situation is on other platforms)?

[nat (Natalie T)]

This plugin’s intention is to help site owners work with email marketing providers to send out more customised brand messaging.

The only provider included in the plugin is Mailchimp for now, so no, this plugin does not work without Mailchimp. It syncs Discourse forum users who opt in, with what Mailchimp defines as an “audience”.

[ked (Kenny DuBose)]

@nat Allow me to suggest providing for Zoho Campaigns in the near future.

[sp-jordan-violet (Jordan Violet)]

One thing I noticed is that, after enabled, the banner didn’t show up for me until I logged in with an incognito browser.

Will there be anything we can do to make sure this shows up for all existing users who’ve gone to the site before?

[JammyDodger]

FWIW, it showed up fine for all my existing test users when I was trying it out.

[Jonathan5]

As with the Subscriptions plugin, it would be good if people could sign up to the newsletter and forum at the same time. I guess it’s only possible for already-registered users.

[JammyDodger]

I think including a box on the create account modal could be good. Though currently they’d see the banner when they sign in, which may be more prominent?

[denvergeeks]

@Jagster I read this in the above Topic Post…

Currently, the plugin supports Mailchimp as the newsletter provider and only one global newsletter for all users. Support for additional providers and newsletters limited to groups is planned for future releases.

[nat (Natalie T)]

@sp-jordan-violet

anything we can do to make sure this shows up for all existing users

I suspect that might be a small blip (caching!) only for your user as you’re the one who turned it on.

The banner logic to get it to show up is very fixed: if the user has never dismissed the banner before, it will show up.

[nathank (Nathan Kershaw)]

How does this plugin handle an existing Audience which already contains many of the community members?

And is there any way to make it function as ‘opt out’ rather than ‘opt in’?
By this I mean that:

1. All who sign up to our site are added to the Audience automatically
2. The banner gives an ‘opt out’ option (or maybe just isn’t displayed at all)

[maiki]

@Jonathan5

As with the Subscriptions plugin, it would be good if people could sign up to the newsletter and forum at the same time. I guess it’s only possible for already-registered users.

The suggestion is nice, since it streamlines the process.

However, as someone who has run mailing lists over years (duration), I’d much prefer to have at least one level of account verification before adding an email to my list. It provides more value over time, and will cause less work over time.

If we made it available on sign-up I think I’d still prefer waiting for them to log in, first.

[Jonathan5]

Yes, you would (as now) require email verification for Discourse membership, and would begin mailing list membership when beginning Discourse membership.

[Jagster (Jakke Lehtonen)]

Is that still legal action somewhere in the western countries?

[nathank (Nathan Kershaw)]

Absolutely, if it is explicit that you will also be signed up to the newsletter as part of joining the site.

It is actually essentially the same request as:

@Jonathan5

it would be good if people could sign up to the newsletter and forum at the same time.

[RGJ (Richard - Communiteq)]

@nathank

Absolutely, if it is explicit that you will also be signed up to the newsletter as part of joining the site.

That is untrue. @Jagster is correct, it’s not legal in EU.

The Dutch telecommunications law requires that the user gives explicit and separate permission for newsletters, and the GDPR has a different ground for processing for the forum and the newsletter. Where the forum can be seen as performance of a contract, the newsletter requires explicit consent.

So you’ll need a separate checkbox at least. And if I remember correctly there is jurisprudention in NL that the checkbox need to be unchecked by default.

That all said, what a great plugin!

[Jonathan5]

I think you agree really. Based on what you have said about explicit and separate consent, it could be made mandatory for the initially unticked email list consent box to be ticked for the person to join the forum.

[Jagster (Jakke Lehtonen)]

@RGJ

jurisprudention in NL

That applies thru EU. Opt-out is just unlegal.

And… it should be big no-no everywhere anyway, because it is just a lousy way to force users receive something they aren’r asked. But hey, it’s good for marketing and users can always delete or mark such newsletter, aka. marketing leads, as a spam

Well, I’m heading to off topic so I’ll jump off from this side branch. But if I’m remembering right Mailchimp is strongly against opt-out.

[Jonathan5]

I should add that when I made the original request what I had in mind was an optional and unticked checkbox for signing up to the email list which would appear on the Discourse signup page. I think that would comply with any sensible interpretation of the EU’s GDPR and of good practice worldwide.

[nathank (Nathan Kershaw)]

@RGJ

The Dutch telecommunications law requires that the user gives explicit and separate permission for newsletters,

Fortunately, I’m not living in the Netherlands (well, not at the moment anyway). There are ‘western’ countries which do not fall under EU law.

Does this include the Activity Summary? It all depends on what the definition of a Newsletter is, and where on the spectrum the thing that actually gets emailed is.

Also, what of a dedicated category with Watching set for all users by default? That could be construed as a newsletter if one had a liberal interpretation.

Having said all that, I’m pretty sure we all agree that sending folk stuff electronically without their consent is definitely bad (and usually illegal). Laws around the world differ in where the exact point of acceptability is.