cymdeveloppement / roundcube-announcement

v1.0.0 2026-10-12 04:45 UTC

Requires

• php: >=8.0
• roundcube/plugin-installer: >=0.3.0

MIT

• Yann Challet

• news
• banner
• roundcube
• webmail
• Announcement
• motd
• roundcube-plugin

Published on Packagist.org on 2026-10-12 04:42 UTC

README

Shows announcements (new features, maintenance, migration notice...) to the users of Roundcube webmail when they open their mailbox, once per user.

Features

• Once per user: an announcement is shown until the user closes it, then never again. Closed announcements are kept in the user preferences: no database table to create.
• Dialog or banner: a modal window, or a box at the top of the screen that leaves the mailbox usable. Default for all announcements, or per announcement.
• HTML file, Markdown file or URL: Markdown is converted with the library shipped with Roundcube 1.7 (GitHub flavor: tables, links...). URLs are loaded by the browser.
• Isolated: the content is shown in a sandboxed frame, its styles do not affect Roundcube and scripts of local files do not run. Links open in a new tab.
• Translations: news.md is replaced with news.fr_FR.md or news.fr.md when it exists, {lang} is replaced in paths and URLs, titles can be translated.
• Dates and targets: start and end dates, regular expression on the login.
• Several announcements are shown one after the other.

Screenshots

Dialog, Markdown announcement:

Banner, HTML announcement:

Requirements

• Roundcube 1.6 or later (1.7 or later for Markdown announcements)
• PHP 8.0 or later

Installation

composer require cymdeveloppement/roundcube-announcement

Then copy and edit the configuration file:

cp plugins/roundcube_announcement/config.inc.php.dist plugins/roundcube_announcement/config.inc.php

Add the plugin to your Roundcube configuration:

$config['plugins'] = ['roundcube_announcement'];

Configuration

All options are documented in config.inc.php.dist.

$config['announcement_list'] = [
    'new-webmail-2026-10' => [
        'source' => 'announcements/new-webmail.md',
        'title'  => ['en_US' => 'New webmail', 'fr_FR' => 'Nouveau webmail'],
        'end'    => '2026-11-30',
    ],
    'maintenance-2026-11-02' => [
        'source'  => 'https://intranet.example.com/maintenance.html?lang={lang}',
        'display' => 'banner',
        'height'  => 120,
        'users'   => '/@example\.com$/',
    ],
];

The key is the ID of the announcement. To show an announcement again to everybody, give it a new ID.

Options of an announcement

All options are optional except source.

Option	Description
source	Required. HTML file (.html), Markdown file (.md, .markdown), absolute or relative to the plugin folder, or http(s) URL. {lang} = language of the user.
type	auto (from the extension), html or markdown.
title	Title, a string or an array of translations.
display	dialog or banner.
start	Shown from this date (2026-10-15, 2026-10-15 08:00...). Without it: shown right away.
end	No longer shown after this date (a date alone includes that day). Without it: no time limit, shown until each user closes it.
users	Regular expression, or list of them, matched against the login.
width	Width of the dialog, in pixels.
height	Height of the content, in pixels. Default: fitted to the content of files, 400 for URLs.
sandbox	URLs only: sandbox attribute of the frame.

Global options

Option	Default	Description
announcement_list	[]	Announcements, see above.
announcement_display	dialog	dialog or banner, when the announcement does not say it.
announcement_dialog_width	640	Default width of the dialog, in pixels.
announcement_style		CSS added to HTML and Markdown announcements.
announcement_url_sandbox	allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox	sandbox attribute of the frame of URL announcements.

How it works

• Announcements are checked each time the mailbox screen is loaded, not only at login: they work with any login method (form, OIDC, SSO, auto-login), and an announcement not closed yet (tab closed, crash) comes back next time.
• When the user closes an announcement, its ID is added to the announcement_seen preference with the date. IDs removed from the configuration are dropped from it at the same time.
• To show the announcements again to a user, remove announcement_seen from their preferences.

Security

HTML and Markdown files are written by the administrator and shown as is (raw HTML is allowed in Markdown). They are shown in a frame without scripts nor forms.

URL announcements are loaded by the browser of the user: the server must allow framing (no X-Frame-Options: DENY, nor a frame-ancestors excluding the webmail). Never add allow-same-origin to the sandbox of a page served by the webmail host itself: it would get access to the Roundcube session.

License

MIT, see LICENSE.