Backend Module

Chapters of this Documentation

A "Mail Queue" module below Site Management lists queue entries with a status filter, an optional tenant filter, search, and pagination.

It is registered with access user, so besides admins it can be granted to non-admin backend users through the group access lists—for example editors who manage a site. It stays hidden until explicitly granted.

Mind the data exposure. The module shows the mail contents of the whole instance, including password resets and other personal data. Grant it only to trusted users, or scope delegated editors to their own site with per-tenant scoping.

Upgrade note. The module moved from System to Site Management and its identifier changed from system_mailqueue to site_mailqueue. If you had granted it to a backend group, re-grant it after updating—the group's module list still references the old identifier. Admin users are unaffected.

The Mail Queue backend module listing open entries: two mails waiting for their next retry with an amber "Queued" badge, and one mail with a red "Failed" badge, each row showing recipient, attempt count, next attempt and the transport error.

List Filters

Status tabs, in order: Open · Queued · Failed · Sent.

Open (the default) shows everything not yet delivered (status <> sent): pending retries, the short-lived sending claim, and permanent failures. This is the view you want on open, so actionable mails are visible without the noise of already-sent rows.
Queued, Failed, and Sent each show one stored status.

Why "Sent" can look empty. Without archive mode, a mail that went out on the first try never creates a row at all—the queue only ever sees mails that failed. "Sent" then holds just the entries that were queued and later delivered. Turn on archive mode if you want every sent mail listed.

Tenant or site. As soon as the queue holds entries with a tenant, a dropdown narrows the list and auto-submits on change. Scoped editors only see their allowed sites.

Search covers the subject, the envelope recipients, and Redirected to addresses—the corrected recipient after Send to address.

Filters (status, tenant, search, page) survive module actions such as Send now, Discard, and Hold: the post-action redirect carries them back to the list.

Actions

Detail view. Click a subject to see the full mail: headers, text body, HTML body rendered in a fully sandboxed iframe, and the attachment list.

Send now. One immediate delivery attempt for a queued or failed mail, regardless of the backoff schedule. Still available under a manual hold, so an admin can release a single mail; blocked under forceHold.

Send to address. Redirect a queued or failed mail to a different recipient, for example after a typo in the original address. Same access as Send now (module grant, tenant-scoped)—the caller can already read the mail, so redirecting it within their tenant adds no exposure.

This is an immediate direct send, not a re-queue. The visible To is rewritten to the corrected address, the existing entry flips to sent rather than creating a new row, the corrected address is recorded on it as Redirected to (list badge plus detail field, searchable), the original envelope recipients stay on the row for audit, and the module stays on the entry's detail view so the outcome is visible.

Send again. Re-send an archived mail. See Archive Mode.

Discard. Remove an entry including its payload file.

Hold all mails. Stop all delivery: every mail is queued instead of sent, with no delivery attempt at all, and flush runs deliver nothing. Meant for planned mail server migrations or for intercepting a batch of mails on a live system. Resuming delivers everything with the next flush run.

While held, the dashboard widget shows a paused state, red webhook alerts are suppressed, and hold and resume each announce themselves once via the webhook. Individual Send now and Send to address still work under this manual hold.

For a permanent, deployment-based hold on a staging or test environment, use forceHold instead—that one cannot be resumed from here on purpose, and it also blocks manual delivery.

The module footer shows the effective configuration at a glance: retries, retentions, alert threshold, and whether the webhook and ops email are configured.

Access Levels

Access is layered so the module can be delegated without handing out the destructive, instance-wide controls.

Action	Needs
List, detail and preview, Send now, Send again	Module grant (access `user`)
Discard (delete a single entry and its payload)	Module grant and discard
Hold all mails and resume (instance-wide)	Module grant and manage
`forceHold` (environment guarantee)	Not togglable here, for anyone

discard and manage are two independent custom access options. Find them under backend user group → tab "Module Permissions" → "Custom module options" → Mail Queue. Admins have both, and a manage user may discard too.

Grant a site editor discard but not manage, and they can delete individual mails without being able to hold the whole instance's delivery. Without either option the Discard and Hold buttons are hidden and the actions are rejected server-side—the editor can still watch the queue and re-send a stuck mail.

The Mail Queue access options on a TYPO3 backend user group: two separate checkboxes, one to discard single queue entries and one to hold and resume all mail delivery, with only the second one ticked.

Per-Tenant Scoping

A non-manage user can be limited to one or more tenants, so a delegated site editor only sees their own site's mail—in the list, in the detail view, and in single-entry delivery, enforced server-side.

There are two equivalent ways, and they are merged as a union:

Backend group field, recommended for editors. On the backend group, tab Mail Queue → "Mail Queue: allowed sites", pick the sites from a multi-select. The list is the instance's configured sites, and new sites appear automatically. Group level only.

TSconfig, for per-user overrides or purely config-based setups:

tx_mailqueue.allowedTenants = b13

Comma-separate several tenants.

A mail’s tenant is its tenant key—the site identifier by default, so both the field and allowedTenants list site identifiers.

Restriction is opt-in: as long as neither a group field nor TSconfig names a tenant, a granted user still sees every tenant’s mail, which is the unchanged behavior. Once any source lists sites, the user is limited to the union of all listed sites. Admins and manage users always see everything.

Hold and resume stay instance-wide and manage-only. Discard needs the separate discard option, see Access Levels.

Language

All labels of the module come from XLIFF files in Resources/Private/Language/—locallang.xlf for the module itself, locallang_db.xlf for the backend group field. English and German ship with the extension; the module follows each backend user's own language setting.

To add another language, drop a translation next to the originals using the TYPO3 naming scheme (<language key>.locallang.xlf, for example fr.locallang.xlf), or use the regular translation server workflow.

To change individual labels without touching the extension, point locallangXMLOverride at your own file in config/system/additional.php:

$GLOBALS['TYPO3_CONF_VARS']['SYS']['locallangXMLOverride']
    ['de']['EXT:mail_queue/Resources/Private/Language/locallang.xlf'][]
        = 'EXT:my_sitepackage/Resources/Private/Language/Overrides/de.mail_queue.xlf';

The override file only needs the trans-unit entries you actually want to change; everything else falls back to the shipped label.