# Discourse Newsletter Integration
**URL:** https://meta.discourse.org/t/discourse-newsletter-integration/275509
**Category:** Plugin
**Tags:** official, newsletter-integration
**Created:** [August 17, 2023, 3:58am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509 "2023-08-17T03:58:38Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [August 17, 2023, 3:58am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/1 "2023-08-17T03:58:39Z")
| | | |
| --- | --- | --- |
| :discourse2: | **Summary** | **Discourse Newsletter Integration** adds customizable newsletter subscription services to your instance. |
| 🛠 | **Repository Link** | [https://github.com/discourse/discourse-newsletter-integration](https://github.com/discourse/discourse-newsletter-integration) |
| 📖 | **Install Guide** | [How to install plugins in Discourse](https://meta.discourse.org/t/install-plugins-in-discourse/19157) |
> [@](#):
>
> :discourse2: As this is an #official plugin maintained by the Discourse team, #Support, #Contribute > Bug, #Contribute > UX, and #Contribute > 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**](https://meta.discourse.org/new-topic?category_id=6&body=%3E%20Before%20asking,%20did%20you%20search%20first%3F%20Press%20%F0%9F%94%8D%20at%20the%20upper%20right%20to%20search.&tags=newsletter-integration "Ask for support on configuring and using Discourse Newsletter Integration") [🐛 **Bug**](https://meta.discourse.org/new-topic?category_id=1&tags=newsletter-integration "A bug report means something is broken, preventing normal/typical use of the plugin") [👀 **UX**](https://meta.discourse.org/new-topic?category_id=9&tags=newsletter-integration "Discussion about the user interface of Discourse Newsletter Integration, and how features are presented (including language and UI elements)") [💡 **Feature**](https://meta.discourse.org/new-topic?category_id=2&tags=newsletter-integration "Discussion about how existing Discourse Newsletter Integration features can be improved or enhanced, and how proposed new features could work")
## 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](https://meta.discourse.org/t/customize-any-text-in-discourse/36092) 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**](https://us1.admin.mailchimp.com/account/api/) 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](https://mailchimp.com/help/about-api-keys/)
#### 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](https://us1.admin.mailchimp.com/lists/settings/defaults)**
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](https://mailchimp.com/help/find-audience-id/)
#### 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.
> :discourse2: Hosted by us? This plugin is available on our Enterprise plan.
> Last edited by @JammyDodger 2024-06-18T14:21:46Z
>
> > **Check document**
> >
> > Perform check on document:
---
### Author:  [@Jagster](https://meta.discourse.org/u/Jagster)
#### Post date: [August 17, 2023, 5:02am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/2 "2023-08-17T05:02:34Z")
Does it work without Mailchimp or is it kind of frontend for services of Mailchimp (as quite typically situation is on other platforms)?
---
### Author:  [@nat](https://meta.discourse.org/u/nat)
#### Post date: [August 17, 2023, 6:46am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/3 "2023-08-17T06:46:19Z")
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”.
---
### Author:  [@ked](https://meta.discourse.org/u/ked)
#### Post date: [August 17, 2023, 9:37pm UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/4 "2023-08-17T21:37:38Z")
@nat Allow me to suggest providing for Zoho Campaigns in the near future.
---
### Author:  [@jordan-violet](https://meta.discourse.org/u/jordan-violet)
#### Post date: [August 20, 2023, 1:12pm UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/6 "2023-08-20T13:12:05Z")
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?
---
### Author:  [@JammyDodger](https://meta.discourse.org/u/JammyDodger)
#### Post date: [August 20, 2023, 1:19pm UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/7 "2023-08-20T13:19:56Z")
FWIW, it showed up fine for all my existing test users when I was trying it out. 👍
---
### Author:  [@Jonathan5](https://meta.discourse.org/u/Jonathan5)
#### Post date: [August 20, 2023, 2:21pm UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/8 "2023-08-20T14:21:08Z")
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.
---
### Author:  [@JammyDodger](https://meta.discourse.org/u/JammyDodger)
#### Post date: [August 20, 2023, 2:26pm UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/9 "2023-08-20T14:26:53Z")
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?
---
### Author:  [@denvergeeks](https://meta.discourse.org/u/denvergeeks)
#### Post date: [August 20, 2023, 8:11pm UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/10 "2023-08-20T20:11:13Z")
@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.
---
### Author:  [@nat](https://meta.discourse.org/u/nat)
#### Post date: [August 21, 2023, 5:54am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/11 "2023-08-21T05:54:43Z")
> [@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](https://github.com/discourse/discourse-newsletter-integration/blob/3493f2ad3f4631ec02782bffe80463412a4dea51/plugin.rb#L90-L99): if the user has never dismissed the banner before, it will show up.
---
### Author:  [@nathank](https://meta.discourse.org/u/nathank)
#### Post date: [August 21, 2023, 10:27am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/12 "2023-08-21T10:27:10Z")
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)
---
### Author:  [@maiki](https://meta.discourse.org/u/maiki)
#### Post date: [August 21, 2023, 8:03pm UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/14 "2023-08-21T20:03:54Z")
> [@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. 🙂
---
### Author:  [@Jonathan5](https://meta.discourse.org/u/Jonathan5)
#### Post date: [August 21, 2023, 10:55pm UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/15 "2023-08-21T22:55:49Z")
Yes, you would (as now) require email verification for Discourse membership, and would begin mailing list membership when beginning Discourse membership.
---
### Author:  [@Jagster](https://meta.discourse.org/u/Jagster)
#### Post date: [August 22, 2023, 5:41am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/16 "2023-08-22T05:41:28Z")
Is that still legal action somewhere in the western countries?
---
### Author:  [@nathank](https://meta.discourse.org/u/nathank)
#### Post date: [August 22, 2023, 6:15am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/17 "2023-08-22T06:15:45Z")
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.
---
### Author:  [@RGJ](https://meta.discourse.org/u/RGJ)
#### Post date: [August 22, 2023, 6:24am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/18 "2023-08-22T06:24:10Z")
> [@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! 😍
---
### Author:  [@Jonathan5](https://meta.discourse.org/u/Jonathan5)
#### Post date: [August 22, 2023, 7:38am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/19 "2023-08-22T07:38:01Z")
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.
---
### Author:  [@Jagster](https://meta.discourse.org/u/Jagster)
#### Post date: [August 22, 2023, 7:42am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/20 "2023-08-22T07:42:49Z")
> [@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.
---
### Author:  [@Jonathan5](https://meta.discourse.org/u/Jonathan5)
#### Post date: [August 22, 2023, 7:51am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/21 "2023-08-22T07:51:37Z")
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.
---
### Author:  [@nathank](https://meta.discourse.org/u/nathank)
#### Post date: [August 24, 2023, 4:49am UTC](https://meta.discourse.org/t/discourse-newsletter-integration/275509/22 "2023-08-24T04:49:23Z")
> [@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.
[Next page](https://meta.discourse.org/t/discourse-newsletter-integration/275509.md?page=2)