---
title: Configuration
url: "https://b13.com/products/mail-queue-for-typo3/documentation/configuration"
date: 2026-09-12
modified: 2026-09-25
lastUpdated: 2026-09-25
---

# Configuration

![Envelope icon with a circular arrow, indicating the action of replying to an email, set against a gradient background.](https://b13.com/fileadmin/_processed_/1/7/csm_sharing-ext-mail-queue-S_91a8e0ced6.webp)

 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:

     Copy

```
$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](https://b13.com/products/mail-queue-for-typo3/documentation/multiple-transports-multi-tenant).

   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](https://b13.com/products/mail-queue-for-typo3/documentation/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](https://b13.com/products/mail-queue-for-typo3/documentation/force-hold-never-send-from-an-environment).

   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](https://b13.com/products/mail-queue-for-typo3/documentation/installation) |
| `MAIL` | `Connections` | Per-tenant SMTP accounts. See [Multiple Transports](https://b13.com/products/mail-queue-for-typo3/documentation/multiple-transports-multi-tenant) |
| `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](https://b13.com/products/mail-queue-for-typo3/documentation/backend-module#c12507) |

 Configuration