cpsit/typo3-mailqueue

TYPO3 CMS extension to improve TYPO3's mail spooler with additional components

0.3.2 2024-03-22 07:27 UTC

Requires

• php: ~8.1.0 || ~8.2.0 || ~8.3.0
• ext-mbstring: *
• psr/http-message: ^1.0 || ^2.0
• symfony/console: ^5.4 || ^6.4 || ^7.0
• symfony/mailer: ^5.4 || ^6.4 || ^7.0
• symfony/mime: ^5.4 || ^6.4 || ^7.0
• typo3/cms-backend: ~11.5.0 || ~12.4.0 || ~13.0.0
• typo3/cms-core: ~11.5.0 || ~12.4.0 || ~13.0.0
• typo3/cms-fluid: ~11.5.0 || ~12.4.0 || ~13.0.0
• typo3fluid/fluid: ^2.7

Requires (Dev)

• armin/editorconfig-cli: ^1.8 || ^2.0
• ergebnis/composer-normalize: ^2.42
• phpstan/extension-installer: ^1.3
• phpstan/phpstan: ^1.10
• phpstan/phpstan-phpunit: ^1.3
• phpstan/phpstan-symfony: ^1.3
• phpunit/phpcov: ^9.0 || ^10.0
• saschaegerer/phpstan-typo3: ^1.10
• ssch/typo3-rector: ^2.0
• typo3/cms-lowlevel: ~11.5.0 || ~12.4.0 || ~13.0.0
• typo3/coding-standards: ^0.8.0@dev
• typo3/testing-framework: ^7.0.2 || ^8.0.9

GPL-2.0-or-later

• Elias Häußler

README

TYPO3 extension mailqueue

📦 Packagist | 🐥 TYPO3 extension repository | 💾 Repository | 🐛 Issue tracker

An extension for TYPO3 CMS that extends TYPO3's mail spooling functionality with an extended queueable mail transport interface. In addition, it provides an improved version of TYPO3's FileSpooler. In order to make mails in the mail queue visible, the extension provides an (admin-only) backend module and console commands to list and flush the mail queue.

🚀 Features

• Extended interface for queueable mail transports
• Improved queueable file transport with failure metadata
• Backend module to list mails in queue
• Console command to list queue and flush mails
• Compatible with TYPO3 11.5 LTS, 12.4 LTS and 13.0

🔥 Installation

Composer

composer require cpsit/typo3-mailqueue

TER

Alternatively, you can download the extension via the TYPO3 extension repository (TER).

⚡ Usage

Note

In order to use a queueable mail transport, you need to configure it in your system settings, along with the required transport settings.

Concept

The extension builds on TYPO3's mail spooling feature. It provides an extended interface CPSIT\Typo3Mailqueue\Mail\Transport\QueueableTransport for TYPO3\CMS\Core\Mail\DelayedTransportInterface with additional methods to enqueue and dequeue mails:

• public function getMailQueue(): Mail\Queue\MailQueue

  Returns an instance of CPSIT\Typo3Mailqueue\Mail\Queue\MailQueue that holds all currently enqueued mails as instances of CPSIT\Typo3Mailqueue\Mail\Queue\MailQueueItem.

• public function enqueue(Mime\RawMessage $message, ?Mailer\Envelope $envelope = null): Mail\Queue\MailQueueItem

  Allows to enqueue a mail to the mail queue. This is basically identical to the send() method provided by the base Symfony\Component\Mailer\Transport\TransportInterface.

• public function dequeue(Mail\Queue\MailQueueItem $item, Mailer\Transport\TransportInterface $transport): bool

  Sends the message of a given mail queue item with the provided "real" transport, effectively dequeuing it from the mail queue. This is basically identical to the flushQueue() method provided by the base TYPO3\CMS\Core\Mail\DelayedTransportInterface with the difference that it only dequeues the given mail queue item and leaves the rest of the queue untouched.

• public function delete(Mail\Queue\MailQueueItem $item): bool

  Deletes the message of a given mail queue item without sending it. The message is also dequeued from the mail queue.

Recoverable transports

Next to the QueueableTransport interface there exists an extended interface CPSIT\Typo3Mailqueue\Mail\Transport\RecoverableTransport. It allows to recover stuck mails with a configured recover timeout:

• public function recover(int $timeout = 900): void

  Recovers mails that are enqueued for longer than the given timeout (in seconds) and are in "sending" state. Recovering a mail resets their mail state from "sending" to "queued". They will then be sent again on dequeue or when the mail queue is flushed.

Backend module

Note

Only administrators can see the backend module.

The backend module lists all currently enqueued mails. In addition, for supported transports it may also show transport failure details. It can be used to get a quick overview about the health state of the mail queue. It also allows to dequeue single mails from the mail queue by sending them with the configured real transport.

Console commands

Flush queue

The extension provides a console command to flush the mail queue:

typo3 mailqueue:flushqueue [-l|--limit] [-r|--recover-timeout] [-j|--json]

The number of mails to be sent can be limited with --limit (or -l). If no limit is passed, the whole mail queue is flushed.

For transports implementing the RecoverableTransport interface, the recover timeout can be configured with --recover-timeout (or -r).

When using --json (or -j), user-oriented output is written to stderr and result messages are written in JSON format to stdout.

List queue

The extension provides a console command to list enqueued mails:

typo3 mailqueue:listqueue [-s|--strict] [-w|--watch]

With --strict (or -s) enabled, the command exits with a non-zero exit code in case any enqueued mail could not be delivered because of a failure.

In addition, a watch mode can be enabled with --watch (or -w) which updates the list every five seconds. The watch mode can be exited with Ctrl+C.

Available transports

The extension provides two custom implementations as XClasses for TYPO3's native mail spoolers:

TYPO3 core implementation	Custom implementation (XClass)
TYPO3\CMS\Core\Mail\FileSpool	CPSIT\Typo3Mailqueue\Mail\Transport\QueueableFileTransport
TYPO3\CMS\Core\Mail\MemorySpool	CPSIT\Typo3Mailqueue\Mail\Transport\QueueableMemoryTransport

📂 Configuration

Mail settings

Queueable mail transports are registered the "normal" way as described in the official TYPO3 core documentation. Add the following to your system configuration (e.g. in additional.php/AdditionalConfiguration.php):

# File transport
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_spool_type'] = 'file';
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_spool_filepath'] = '/path/to/mailqueue';

# Memory transport
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_spool_type'] = 'memory';

# Use any other custom mail transport
# Note: Custom transports must implement CPSIT\Typo3Mailqueue\Mail\Transport\QueueableTransport interface!
$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_spool_type'] = \Vendor\Extension\Mail\Transport\CustomQueueableTransport::class;

Extension configuration

The following extension configuration options are available:

Configuration key	Description	Required	Default
queue.delayThreshold	Number in seconds after which a mail in the queue is considered "delayed"	–	1800
pagination.itemsPerPage	Number of mails to display on a single page in backend module	–	20

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

💎 Credits

The extension icon ("envelope-open") as well as the icon for the backend module are modified versions of the original actions-envelope-open icon from TYPO3 core which is originally licensed under MIT License.

⭐ License

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