How It Works

Chapters of this Documentation

The Delivery Path

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 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 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.

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.