Digest Mail — Periodic email digests for Flarum 2.x

stryguardian

I've been working on a digest email extension for Flarum 2.x and I think it's ready for people to try out. This extension requires server setup for mail sending. I tried to include all the setup instructions needed for various server setups in the admin panel under "Server Settings," but if you are not comfortable working in CLI, you may want to seek help or tutorials to get this done.

📬️ What it does

Instead of sending a separate notification every time something happens on your forum, Digest Mail sends your members one summary email per period — daily, weekly, or monthly, whichever they prefer. Each email covers what happened since their last digest: new discussions, the most active threads, discussions they haven't read yet, new members who joined, and a stats bar showing overall forum activity for the period.
Members set their own frequency from their account settings page, and every email includes a one-click unsubscribe link that takes them to a preference page where they can change their frequency or opt out entirely. As an admin you can restrict which frequency options are available — if your forum is low-traffic you might offer only weekly and monthly and disable daily entirely. Daily is disabled by default.

⏬️ Installation

composer require resofire/digest-mail

📧 What goes in the email

The core sections are always included: new discussions, active discussions, unread discussions personalised to each recipient, new members, favorite discussions ranked by likes or reactions, and a community stats summary.

There are also optional sections that appear automatically when you have the relevant extension installed and enabled:

Leaderboard — top point-earners for the period, with movement indicators and a biggest-mover spotlight. Requires huseyinfiliz/leaderboard.
Badges — recent badge earners, the most-awarded badge, and the rarest badge awarded during the period. Requires fof/badges.
Pick'em — upcoming matches members can still vote on, recent results, and current standings. Requires huseyinfiliz/pickem.
Gamepedia — most-discussed game pages and newly added games for the period. Requires huseyinfiliz/gamepedia.
Awards — active and upcoming awards with voting deadlines, vote totals, and current front-runners. Requires huseyinfiliz/awards.

If you have fof/reactions installed, the favorite discussions section shows a per-emoji reaction breakdown instead of just a like count.

🌈 Layout and branding

The email uses your forum's configured brand colours automatically — headings, buttons, and accent elements all pull from your primary and secondary colour settings. The layout is table-based HTML that renders correctly in Gmail, Outlook, Apple Mail, and mobile clients.

🎛️ Admin panel

The extension adds a page to your admin panel with four tabs. The Settings tab covers content limits for each section, the send schedule, timezone, frequency options, and integration toggles. The Digest Order tab lets you reorder the sections with arrows — changes apply immediately to all future sends. The Statistics tab shows your subscription overview, subscribers per frequency, last sent dates, and send history. The Server Settings tab has everything related to how the extension runs on your server.
There's also a test send tool that lets you send a live digest email to any address immediately without affecting any subscriber records.

⏲️ Scheduling

You set the time and timezone you want emails to go out — the extension fires at that time in your chosen timezone, not the server's. You can configure a single send hour or a send window — for example 2 a.m. to 5 a.m. — which spreads sending across several hours and keeps server load low on larger forums. The extension tracks its own progress and stops automatically once all subscribers have been processed.

🖥️ Server setup

This extension requires a working outbound mail configuration in your Flarum admin panel and a cron job running the Flarum scheduler every minute — which is a standard requirement shared by many Flarum extensions, so you may already have it.

For small forums, the default sync driver works fine. What you really want is a background queue driver to keep your forum responsive during sends. Flarum 2.x has a database queue driver built into core that handles this with just a small change to your config.php and one additional cron line. For larger forums, Redis or Valkey with Horizon and Supervisor is the most capable option. You will likely never need this option, but it exists if you do. The Server Settings page in the admin panel walks you through each approach with ready-to-copy configurations for your specific server.

🖼️ Screenshots

Links
Github
Packagist
License: MIT

ernestdefoe

stryguardian this is awesome. I am installing now @KBExit hope you got things setup so I can use it.

rob006

Does it work for Flarum 1.8? Because there are releases marked as compatible with this version of Flarum: https://packagist.org/packages/resofire/digest-mail#v0.3.6

stryguardian

rob006 There is a fully functional version for 1.8, which I am running on my site. I only announced it for 2.x because this is the version that will receive updates from this point forward. If there are new features to be added, it will be the 2.x version to receive those new features.

Capybara

The admin settings look really nice. Looking forward to it appearing on Weblate so I can translate the extension

treyb

stryguardian

Hey, just wanted to give you a heads-up on a conflict I ran into when enabling this extension.

If you have blomstra/digest installed, the migration in resofire/digest-mail will fail with a duplicate column error on ct_users — specifically digest_frequency and digest_last_sent_at. Blomstra's extension already adds those columns, so when yours tries to do the same thing it throws a PDOException.

Workaround for anyone who hits this: manually insert the migration record into ct_migrations to mark it as already run and skip the duplicate ALTER.

Might be worth adding a hasColumn check in the migration so it fails gracefully when those columns are already present. Happy to share the full error log if that helps. Thanks for the extension!

treyb

@stryguardian , I also am curious if there are plans, or if you have a way to have user opt in by default, at signup?

ernestdefoe

treyb that would be nice to have a way to agree at signup.

treyb

ernestdefoe My little hackey version of this pulls directly from the user table, and I have in my TOS that you agree to receive weekly emails until you opt out.

jstebenne

I tried sending a test email, but it failed. I found in the logs that the extension is trying to query for approved post (column is_approved), but is failing since I did not have the Approval extension enabled (it is disabled because of a bug).

I don't think the extension should assume that the Approval extension is present, but I understand why it is included in the query.

The relevant code is here: ResofireV2/digest-mailblob/2.x/src/DigestQuery.php#L756-L777

ernestdefoe

@stryguardian what does it mean in the settings what does this mean?

jstebenne

It would also be great to have a way to change the language of the digest. I was able to translate user options using the Linguist extension, but none of the email text can be edited through it.

treyb

I figured out how to auto opt in @ernestdefoe

If you want all users defaulted to weekly (or daily/monthly) digests instead of leaving them on "Off", here's how to do it in two parts.

1. Backfill existing users with a one-time SQL query

Run this directly in your database. It only updates users who haven't made a choice yet, so it won't override anyone who deliberately turned digests off:

UPDATE users 
SET digest_frequency = 'weekly' 
WHERE digest_frequency IS NULL
AND is_email_confirmed = 1;

Swap weekly for daily or monthly depending on your preference. Note: if your Flarum install uses a table prefix (e.g. ct_), use the full prefixed name — so ct_users instead of users.

2. Auto opt-in new registrations going forward

Add this to your extend.php in your Flarum root. The key thing here is to use the unprefixed table name, Flarum's database connection applies the prefix automatically, so passing users is correct even if your actual table is ct_users:

use Flarum\Extend;
use Flarum\User\Event\Registered;

// inside your return array:
(new Extend\Event())
    ->listen(Registered::class, function (Registered $event) {
        resolve('db')->table('users')
            ->where('id', $event->user->id)
            ->update(['digest_frequency' => 'weekly']);
    }),

Then clear cache:

php flarum cache:clear

That's it. New signups will now be set to weekly automatically.

luceos

treyb you are using resolve here. A function that is native to Laravel and recommended against with Flarum. In this case it doesn't make sense because you already have the respective user available, hence your ability to use their Id.

Here is another version compatible with Flarum conventions;

use Flarum\Extend;
use Flarum\User\Event\Registered;

// inside your return array:
(new Extend\Event())
    ->listen(Registered::class, function (Registered $event) {
        $event->user->digest_frequency = 'weekly';
        $event->user->save();
    }),

👍

stryguardian

Update: v2.2.1

Fixed: Missed a hasColumn check for a migration that added 3 columns to the database and could cause errors if those columns already existed. That is now corrected.

Added: The admin panel now contains 3 options for user onboarding:

No Default - Users choose their own preference
Auto-enroll new users -- Admins can choose to auto-enroll new users into Daily, Weekly or Monthly digests. If you want to use this option, you may want to state this in your ToS.
Show opt-in modal -- This shows a modal (shown below) that appears to new user sign ups after they click to confirm their email address. Clicking the X to dismiss the modal or No Thanks will set their digest frequency to off and the modal will not reappear.

stryguardian

ernestdefoe This was put in place when testing Unsubscribe functions to check whether unsubscribe tokens were valid or invalid. I left it in because there are very rare edge cases, where a user might have issues with their tokens and it would help to have an easy, admin-accessible way to check the validity of their token.

Capybara I hope to do this soon.

stryguardian

I also left the Pick 'em integration in this version. I don't believe that has been ported over to 2.x yet, so it won't work for the time being. If that extension is ported over I will check what changes, if any, there are and adjust accordingly. If it doesn't get ported over, then I will eventually remove that integration.

ernestdefoe

stryguardian after talking with @huseyinfiliz it will get ported over with some hopefully awesome updates. Gonna donate some money soon to hopefully speed up the process.

stryguardian

ernestdefoe oh good. New features may mean more digest possibilities.

ernestdefoe

stryguardian well we are hoping to integrate an API that auto creates things so it doesn't take forever to get games/matches setup and picking winners and such. So not sure what more possibilities there will be. I do know he plans to add Badges support at some point as well.