---
title: Console Commands
url: "https://b13.com/products/mail-queue-for-typo3/documentation/console-commands"
date: 2026-09-12
modified: 2026-09-25
lastUpdated: 2026-09-25
---

# Console Commands

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

  | Command | When | Purpose |
|---|---|---|
| `mailqueue:flush` | Every minute | Deliver due `queued` entries, up to 50 per run; evaluate webhook health |
| `mailqueue:cleanup` | Daily | Drop aged `sent` and `failed` rows—and optionally `queued`—plus payload files and orphan files |
| `mailqueue:purge` | Ad hoc | Wipe one status (`queued`, `failed`, or `sent`) with `--dry-run` and `--force` |
| `mailqueue:send-test` | Smoke test | Send a test mail through the same spool path; `--attachment` hits the file-backed path |

   mailqueue:flush
-----------------

     Copy

```
* * * * *  cd /path/to/project && vendor/bin/typo3 mailqueue:flush
```

  This is the job that makes the queue a queue. **Without it, failed mails stay queued forever.**

Each run delivers at most 50 due entries, so a large backlog drains at roughly 50 mails per minute. Before delivering, the run recovers entries stuck in `sending` from a crashed previous run—anything claimed for more than 15 minutes goes back to `queued`.

The run also evaluates queue health and fires the [alert webhook](https://b13.com/products/mail-queue-for-typo3/documentation/webhook-alerting) on a state change. Under a hold it delivers nothing but still evaluates health, so the widget reflects the growing queue.

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

   mailqueue:cleanup
-------------------

     Copy

```
15 3 * * *  cd /path/to/project && vendor/bin/typo3 mailqueue:cleanup
```

  Removes, after the configured retentions:

- `sent` entries older than `sentRetentionDays` (30 days by default)
- `failed` entries **without** a payload file, older than `failedRetentionDays` (90 days by default)
- `failed` entries **with** a payload file, after the shorter `attachmentRetentionDays` (14 days by default). The two failed retentions are mutually exclusive—each entry falls under exactly one of them, depending on whether its payload lives in a file
- `queued` entries older than `queuedRetentionDays`—**only** when that is set to a positive value; the default `0` disables it so production retries are never dropped early
- The payload files belonging to those rows, plus a date-based sweep for orphaned files

   mailqueue:purge
-----------------

     Copy

```
vendor/bin/typo3 mailqueue:purge --status=queued --dry-run   # preview the count
vendor/bin/typo3 mailqueue:purge --status=queued --force     # delete rows and payload files
```

  Wipes one status in one go, rows and payload files together. `--status` defaults to `queued`; `failed` and `sent` are allowed the same way. `--force` (short: `-f`) is required for the destructive run; without it, nothing is deleted.

The typical use is clearing a staging queue that accumulated under [force hold](https://b13.com/products/mail-queue-for-typo3/documentation/force-hold-never-send-from-an-environment), or cleaning up after a load test.

   mailqueue:send-test
---------------------

     Copy

```
vendor/bin/typo3 mailqueue:send-test you@example.com               # plain mail
vendor/bin/typo3 mailqueue:send-test you@example.com --attachment  # file-backed queue path
```

  Sends a test mail through the exact same path as any application mail, including the spool. That is what makes it a real smoke test rather than a transport check.

`--attachment` (short: `-a`) attaches a small generated file. Mind that the payload only reaches `var/mailqueue/` when delivery fails, or with [archive mode](https://b13.com/products/mail-queue-for-typo3/documentation/archive-mode) on—on a healthy SMTP server the mail just goes out. See [Smoke Test](https://b13.com/products/mail-queue-for-typo3/documentation/installation#c12484) for how to verify the file-backed path deliberately.

 Console Commands