konradmichalik / typo3-letterbox

0.1.0 2026-10-30 10:26 UTC

Requires

• php: ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
• ext-dom: *
• ext-filter: *
• ext-mbstring: *
• masterminds/html5: ^2.10.0
• psr/event-dispatcher: ^1.0
• psr/http-factory: ^1.1.0
• psr/http-message: ^1.1 || ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• psr/log: ^3.0.1
• symfony/console: ^7.2
• symfony/dependency-injection: ^7.2
• symfony/http-foundation: ^7.4.19
• symfony/mailer: ^7.2
• symfony/mime: ^7.2
• typo3/cms-backend: ^13.4 || ^14.0
• typo3/cms-core: ^13.4 || ^14.0
• typo3/cms-frontend: ^13.4 || ^14.0
• zbateson/mail-mime-parser: ^4.0.8

Requires (Dev)

• ext-posix: *
• eliashaeussler/typo3-vendor-bundler: ^4.1.1
• eliashaeussler/version-bumper: ^4.1.2
• konradmichalik/ttt: ^0.4.0
• phpunit/phpcov: ^10.0.1 || ^11.0.4 || ^12.0 || ^13.1.0
• phpunit/phpunit: ^11.0 || ^12.0 || ^13.0
• symfony/config: ^7.2
• typo3/cms-base-distribution: ^13.4 || ^14.0
• typo3/cms-dashboard: ^13.4 || ^14.0
• typo3/cms-lowlevel: ^13.4 || ^14.0
• typo3/cms-reports: ^13.4 || ^14.0
• typo3/testing-framework: ^9.1 || ^10.0

Suggests

• typo3/cms-dashboard: Adds the recent mails dashboard widget
• typo3/cms-reports: Shows the mail catcher status in Admin Tools > Reports

GPL-2.0-or-later

• Konrad Michalik
• Armin Vieweg

Published on Packagist.org on 2026-10-30 10:28 UTC

README

TYPO3 extension typo3_letterbox

Catches TYPO3 mails in an mbox file and shows them in the backend, for local, stage and test systems.

Note

Test systems must not send real mails to real people, but testers need to see what a mail looks like. Letterbox catches outgoing mails in a local mbox file and shows them in the backend, so nothing leaves the system.

✨ Features

• Mail transport that catches every mail in a local mbox file and delivers none
• Backend module under System › Letterbox with search, filters, per-user unread state and a sandboxed HTML preview
• Checks per mail, such as images without alt, http links and tracking pixels
• Sendmail intake for mails that bypass the TYPO3 mailer, such as PHP mail()
• External access for test systems: a token-protected JSON API and a read-only tester inbox
• Retention and console commands to keep the mbox file small

🔥 Installation

Requirements

• TYPO3 13.4 LTS or 14.3 LTS
• PHP 8.2 to 8.5

Composer

composer require konradmichalik/typo3-letterbox

TER

Download the zip file from TYPO3 extension repository (TER).

🚀 Quick start

Turn on "Catch mails with Letterbox" (enable) in Admin Tools › Settings › Extension Configuration › typo3_letterbox (System › Settings in TYPO3 14) and flush the caches. Letterbox then takes over the mail transport, an existing MAIL/dsn included, and writes caught mails to var/letterbox/mails.mbox. Set LETTERBOX_ENABLE=1 or 0 to switch it per system, see configuration.

Alternatively, set the transport in config/system/additional.php:

$GLOBALS['TYPO3_CONF_VARS']['MAIL']['dsn'] = '';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] = \KonradMichalik\Typo3Letterbox\Mail\LetterboxTransport::class;
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_mbox_file'] = '/var/www/mbox/mails.mbox';

Warning

If MAIL/dsn is not empty, TYPO3 core ignores MAIL/transport and sends live through the DSN. Letterbox is bypassed. Keep dsn empty. The switch clears it for you.

Then open System › Letterbox as an administrator. Letterbox is either on and catches every mail, or off and changes nothing.

📚 Documentation

Page	What's inside
Configuration	The switch, transport settings, caught mails and extension settings
Backend module	Search, filters, tabs, checks, preview, navigation, delete and clear
Operations	Retention, console commands, sendmail intake, toolbar item, Reports status and dashboard widget
External access	Activation, the shared token, guard reasons and the tester inbox
JSON API	Endpoints, authentication, response shape, Playwright example
Test mails	Console command letterbox:testmails:send

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

💎 Credits

Letterbox is forked from t3/mbox by Armin Vieweg. The mbox parser approach comes from armin/mbox-parser.

The illustration for the empty and unselected states is "Empty mailbox" by Katerina Limpitsouni from unDraw, recoloured. It is used under the unDraw license and is not covered by the GPL of this extension.

⭐ License

This project is licensed under GNU General Public License 2.0 (or later).