---
title: "Command Controller"
manual: "Mail system"
version: "4.3"
permalink: "https://docs.typo3.org/permalink/mediaessenz/mail:command-controller@4.3"
source: "Reference/CommandController/Index.rst"
rendered: "2026-11-05T22:41:23+00:00"
---

# Command Controller {#command-controller}

MAIL comes with different command controller, which all can be added as task inside the TYPO3 scheduler module.

-   [MassMailingCommand](https://docs.typo3.org/permalink/mediaessenz/mail:massmailingcommand@4.3)
-   [RetryFailedCommand](https://docs.typo3.org/permalink/mediaessenz/mail:retryfailedcommand@4.3)
-   [QueueCleanupCommand](https://docs.typo3.org/permalink/mediaessenz/mail:queuecleanupcommand@4.3)
-   [QueuePurgeCommand](https://docs.typo3.org/permalink/mediaessenz/mail:queuepurgecommand@4.3)
-   [AnalyzeBounceMailCommand](https://docs.typo3.org/permalink/mediaessenz/mail:analyzebouncemailcommand@4.3)
-   [SpoolSendCommand](https://docs.typo3.org/permalink/mediaessenz/mail:spoolsendcommand@4.3)
-   [ClearScssParserCacheCommand](https://docs.typo3.org/permalink/mediaessenz/mail:clearscssparsercachecommand@4.3)

## MassMailingCommand {#mass-mailing-command-controller}

This command is responsible for adding scheduled mailings to the sending queue.
There are two mandatory parameters:

-   site-identifier
-   send-per-cycle

The first one (site-identifier) is the identifier of the site configuration where MAIL can find its recipient sources configuration.
You can find it inside the TYPO3 sites module under the "General" tab.

The second (send-per-cycle) determine how many mails should be sent per cycle.

The time between a cycle can be defined in the "Frequency" field of a task.
e.g. `* * * * *` will run the task every minute, if you put `50` into the send-per-cycle field, 50 Mails per minute will be sent.

The number of send-per-cycle is a limit for the whole run, no matter how many recipient sources a mail uses.

After each cycle the command also retries recipients whose delivery failed before (see [Send queue](https://docs.typo3.org/permalink/mediaessenz/mail:send-queue@4.3)). If another
run of this command or of [mail:retry-failed](https://docs.typo3.org/permalink/mediaessenz/mail:retry-failed-command-controller@4.3) is still active, the new run ends
immediately without sending anything, so that no mail is delivered twice.

## RetryFailedCommand {#retry-failed-command-controller}

Delivers the queued recipients whose retry time is reached, puts deliveries that got stuck back into the queue and
checks the queue health for the [alert webhook](https://docs.typo3.org/permalink/mediaessenz/mail:send-queue-alerting@4.3).

The command [mail:mass-mailing](https://docs.typo3.org/permalink/mediaessenz/mail:mass-mailing-command-controller@4.3) does the same after each cycle. You only need
this command as an own scheduler task, if you want to run the retries more often than the mass mailing or if you
send mails with another command.

-   **site-identifier**

    -   *type:* string
    -   *Default:*

    Identifier of the site configuration, like for the mass mailing. Mandatory if the command runs without a request,
    for example in a scheduler task.

-   **limit**

    -   *type:* int
    -   *Default:* 50

    Maximum number of deliveries per run.

**Example, run every minute by a scheduler task or cron job**

```bash
vendor/bin/typo3 mail:retry-failed --site-identifier=main --limit=50
```

## QueueCleanupCommand {#queue-cleanup-command-controller}

Removes entries from the send queue that are not needed anymore: delivered entries after
[sentRetentionDays](https://docs.typo3.org/permalink/mediaessenz/mail:extension-configuration-sent-retention-days@4.3) and failed entries after
[failedRetentionDays](https://docs.typo3.org/permalink/mediaessenz/mail:extension-configuration-failed-retention-days@4.3). Entries that wait for a retry are never
removed. The command has no arguments.

A daily scheduler task is enough.

**Example**

```bash
vendor/bin/typo3 mail:queue-cleanup
```

## QueuePurgeCommand {#queue-purge-command-controller}

Deletes all entries of the send queue with a given status, regardless of their age. Use it for example to remove
failed entries, after you have fixed the reason, so that the [alert](https://docs.typo3.org/permalink/mediaessenz/mail:send-queue-alerting@4.3) can recover.

-   **status**

    -   *type:* string
    -   *Default:* queued

    One of `queued` (waiting for a retry), `failed` or `sent`. Other values are rejected.

-   **dry-run**

    -   *type:* bool
    -   *Default:* false

    Only shows how many entries would be deleted. Nothing is deleted, even if `--force` is given.

-   **force**

    -   *type:* bool
    -   *Default:* false

    Required to actually delete. Without it the command only shows how many entries would be deleted.
    Short form: `-f`.

> [!WARNING]
> Deleted queue entries are not delivered anymore. If you delete entries with the status `queued`, these recipients do
> not receive the mail.

**Show how many failed entries exist, then delete them**

```bash
vendor/bin/typo3 mail:queue-purge --status=failed
vendor/bin/typo3 mail:queue-purge --status=failed --force
```

## AnalyzeBounceMailCommand {#analyze-bounce-mail-command-controller}

This command fetches returned mails from the mail account defined in the return-path field of the MAIL configuration module
and adds them to the report of the corresponding mail.

A returned mail is assigned to its recipient by the header `X-TYPO3MID`, which is found in the quoted original of the
returned mail. The type and the reason of the return are taken from the delivery status notification (RFC 3464) of the
mail server: the status code (e.g. 5.1.1 for an unknown recipient, 5.2.2 for a full mailbox, 4.x.x for a temporary problem)
and the diagnostic message. Only if there is no notification, the text that the mail server wrote is searched for known
phrases. The quoted original of your mailing is never taken into account. Auto replies (out of office) and delivery
receipts are ignored and deleted from the mailbox. A recipient is counted once per mailing, also if the mail server returns
the mail several times.

See [the report](https://docs.typo3.org/permalink/mediaessenz/mail:mail-report-returned@4.3) for the categories and [RecipientBouncedEvent](https://docs.typo3.org/permalink/mediaessenz/mail:events-recipient-bounced@4.3) to react on a bounce.

Options:

-   **`--server`, `--port`, `--user`, `--password`**

    The IMAP account of the return-path address. The port is 993 by default.

-   **`--limit`**

    Maximum number of messages that are processed per run (0 = no limit).

-   **`--unseen-only`**

    Only process messages that are not flagged as seen. This is faster for a mailbox with many foreign messages, but a
    returned mail that someone has already opened in a mail program is skipped.

-   **`--dry-run`**

    Shows how every message is classified (type, reason, SMTP code, status and the explanation of the mail server).
    Nothing is stored, deleted or flagged. Use it to check a mailbox, for example after the update.

Messages that are stored or ignored are deleted. Messages that cannot be assigned to a mailing are flagged as seen and stay
in the mailbox. A message that causes an error stays untouched and is tried again with the next run, the other messages
are processed anyway. At the end the command prints how many messages were stored, ignored, not assignable or failed.

## SpoolSendCommand {#spool-send-command-controller}

This command controller can be used to send mail in a queue.
It's basically the same coming with TYPO3, but it uses a site specific mail transport configuration.
See site configuration `Transport.yaml` under Integration up in this manuel.
To make this command controller work, it is also necessary to set `transport_spool_type` to `file` or `memory`. if the type was set to `file`, the `transport_spool_type` has to be set as well, e.g. to `upload/tx_mailspool/`.
This command controller is not really needed by this extension, since the sending is already queued by the MassMailingCommand.
But if a developer wants to use the extended Mail-Classes `MEDIAESSENZ\Mail\Mail\Mailer` or `MEDIAESSENZ\Mail\Mail\MailMessage` inside their own extension, it can be usefully.

## ClearScssParserCacheCommand {#clear-scss-parser-cache-command-controller}

This command controller clears the scss parser cache files located in typo3temp/assets/mail/css.
This cache is also cleared after a mail report is deleted.