---
title: How It Works
url: "https://b13.com/products/mail-queue-for-typo3/documentation/how-it-works"
date: 2026-09-12
modified: 2026-09-25
lastUpdated: 2026-09-25
---

# How It Works

![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)

   The Delivery Path
-------------------

     Copy

```
MailerInterface->send()
      │
      ▼
SendFirstSpool (DelayedTransportInterface)
      │
      ├─ immediate delivery via the real transport ──▶ done (normal case)
      │
      └─ TransportException
              │
              ├─ permanent (5xx)
              │        └──▶ recorded as "failed" (payload kept for
              │             manual re-delivery) + ops notification
              │
              └─ transient (4xx, connection error)
                       └──▶ tx_mailqueue_message (status "queued");
                            payloads of mails WITH attachments go to a
                            file in var/mailqueue/ instead of the DB
                                 │
                                 ▼
                    mailqueue:flush—backoff 1 min → 5 min → 15 min
                    → 1 h → every 4 h; after max attempts (default 20,
                    ≈ 2.5 days) → "failed" + ops notification
```

  The important part is what does not happen: in the normal case nothing sits between the request and SMTP. The queue is a catch net, not a buffer.

   Transient Versus Permanent
----------------------------

SMTP 4xx replies and connection problems are retried. A 5xx reply (unknown recipient and the like) is recorded as `failed` immediately, so a broken address is not hammered for days. The payload stays available for inspection and manual re-delivery until cleanup removes it.

The SMTP reply code usually rides along in the transport exception's code. Some exceptions carry it only in the message ("Expected response code 250 but got code 421 …"), which is read as a fallback.

   Statuses
----------

| Status | Meaning |
|---|---|
| `queued` | Waiting for the next retry |
| `sending` | Short-lived claim while a flush run delivers. No module tab; claims stuck for more than 15 minutes recover to `queued` on the next flush |
| `sent` | Delivered. The payload is dropped, unless [archive mode](https://b13.com/products/mail-queue-for-typo3/documentation/archive-mode) is on |
| `failed` | Given up—exhausted retries or a permanent 5xx. The payload is kept for inspection and manual re-delivery until cleanup |

   Backoff Schedule
------------------

Waiting time before the next attempt, by attempts already made:

| Attempts Made | Next Attempt After |
|---|---|
| 1 | 1 minute |
| 2 | 5 minutes |
| 3 | 15 minutes |
| 4 | 1 hour |
| 5 and beyond | 4 hours |

With the default `maxAttempts` of 20 that spans roughly two and a half days (61 hours) before an entry is marked failed.

   Attachments
-------------

The serialized payload of a mail with attachments is written **once** to a file below `var/mailqueue/`, outside the docroot, instead of bloating the database. Retries only read that file—nothing is re-generated or re-encoded per attempt.

The file is removed on successful delivery—unless [archive mode](https://b13.com/products/mail-queue-for-typo3/documentation/archive-mode) is on, in which case it stays until the sent retention removes it. Failed attachment mails get their own, shorter retention (`attachmentRetentionDays`, 14 days by default) to limit disk usage.

If the payload file cannot be read, the entry is kept `queued` with a clear error rather than burned on `failed`. That case is almost always a fixable infrastructure problem—see [the `var/mailqueue/` notes](https://b13.com/products/mail-queue-for-typo3/documentation/installation#c12483).

   Flush Batch Size
------------------

Each `mailqueue:flush` run delivers at most 50 due entries. With the recommended every-minute schedule that is usually enough; a large backlog drains at roughly 50 mails per minute.

   Cleanup
---------

The delivered payload is removed from the row on success. `mailqueue:cleanup` removes old `sent` and `failed` entries—and, when `queuedRetentionDays` is set, aged `queued` ones—together with their payload files, plus a date-based sweep for orphaned files, after the configured retentions.

   Compatibility Note
--------------------

TYPO3's own `mailer:spool:send` also flushes this queue.

 How It Works