Documentation
TYPO3 Extension “Mail Queue”
Version 1.7.0 (2026-09-12)
Most settings live in the extension configuration: Settings → Extension Configuration → mail_queue. They can equally be set in PHP:
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['mail_queue']['<setting>'] = <value>;The per-tenant connection map is the exception—it is set only in PHP, see Multiple Transports.
Settings
| Setting | Default | Purpose |
|---|---|---|
smtpTimeout | 10 | Timeout in seconds for the immediate delivery attempt. Keeps a hanging mail server from blocking requests |
maxAttempts | 20 | Retry attempts before a mail is marked failed—roughly two and a half days with the default backoff |
opsNotificationEmail | (empty) | Address notified when a mail is marked failed: immediately for permanent 5xx failures, after exhausted retries otherwise. Empty disables notifications |
sentRetentionDays | 30 | Retention for entries with status sent—flush successes and, with archive mode, first-delivery archives |
failedRetentionDays | 90 | Retention for failed entries |
attachmentRetentionDays | 14 | Shorter retention for failed entries whose payload lives as a file, to limit disk usage |
queuedRetentionDays | 0 | Retention for still-queued entries; 0 disables it. Set this on staging with forceHold, or the queue cannot stop growing |
alertThresholdMinutes | 30 | The widget turns red and the webhook fires when a mail is undeliverable for longer than this |
alertWebhookUrl | (empty) | Set this in production. HTTPS webhook fired when health turns red, independent of SMTP. Empty disables it |
notifyOnRecovery | 1 | Also notify the webhook when queue health leaves the red state |
archiveMode | 0 | Keep all sent mails, including content, until the sent retention removes them; enables re-sending from the module |
forceHold | 0 | Environment-level "never send" hold. Deployment-based, so it survives a database import from production |
tenants | (none) | Optional map of tenant key → MAIL connection name when several tenants share one transport. PHP only, not in the Extension Manager form |
The Two Settings That Cost You Mails
alertWebhookUrl in production. Leaving it empty means your only failure signal is opsNotificationEmail—an email, sent through the transport that is probably the broken part. See Webhook Alerting.
queuedRetentionDays under forceHold. Force hold queues every mail forever. Without a positive retention, the queue table and var/mailqueue/ grow for as long as the environment runs. See Force Hold.
Related Configuration Outside the Extension
| Where | Setting | Why It Matters |
|---|---|---|
MAIL | transport_spool_type | Must be \B13\MailQueue\Mail\SendFirstSpool::class, or the extension does nothing. See Installation |
MAIL | Connections | Per-tenant SMTP accounts. See Multiple Transports |
SYS | fileCreateMask, folderCreateMask, createGroup | Applied to var/mailqueue/ and its files, so the flush user can read what the web-server user wrote |
| Backend user or group TSconfig | tx_mailqueue.allowedTenants | Limits a user to their own sites. Resolved TSconfig, so both levels count. See Per-Tenant Scoping |
Configuration