---
title: "MAIL settings"
manual: "TYPO3 Explained"
version: "14.3"
permalink: "https://docs.typo3.org/permalink/t3coreapi:typo3confvars-mail@14.3"
source: "Configuration/Typo3ConfVars/MAIL.rst"
rendered: "2026-09-22T13:48:57+00:00"
---

# MAIL settings {#typo3confvars-mail}

You can test the email settings in module **Environment > Test Mail Setup**.
See also [Test mail setup](https://docs.typo3.org/permalink/t3coreapi:environment-test-mail-setup@14.3).

The following configuration variables can be used to configure settings for
the sending of mails by TYPO3:

The configuration values listed here are keys in the global PHP array
`$GLOBALS['TYPO3_CONF_VARS']['MAIL']`.

This variable can be set in one of the following files:

-   [config/system/settings.php](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-settings@14.3)
-   [config/system/additional.php](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-additional@14.3)

-   **format**

    -   *Type:* dropdown
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['format'\]
    -   *Default:* 'both'

    **Allowed values**

    -   **html**

        Send emails only in HTML format

    -   **txt**

        Send emails only in plain text format

    -   **both**

        Send emails in HTML and plain text format

    The [Mailer API](https://docs.typo3.org/permalink/t3coreapi:mail@14.3) allows to send out templated emails, which can be configured
    on a system-level to send out HTML-based emails or plain text emails, or
    emails with both variants.

-   **layoutRootPaths**

    -   *Type:* array
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['layoutRootPaths'\]

    **Default values**

    **Default value of $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['layoutRootPaths'\]**

    ```php
    [
        0 => 'EXT:core/Resources/Private/Layouts/',
        10 => 'EXT:backend/Resources/Private/Layouts/'
    ]
    ```

    List of paths to look for layouts for templated emails. Should be specified
    as .txt and .html files.

-   **partialRootPaths**

    -   *Type:* array
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['partialRootPaths'\]

    **Default values**

    **Default value of $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['partialRootPaths'\]**

    ```php
    [
        0 => 'EXT:core/Resources/Private/Partials/',
        10 => 'EXT:backend/Resources/Private/Partials/'
    ]
    ```

    List of paths to look for partials for templated emails. Should be
    specified as .txt and .html files.

-   **templateRootPaths**

    -   *Type:* array
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['templateRootPaths'\]

    **Default values**

    **Default value of $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['templateRootPaths'\]**

    ```php
    [
        0 => 'EXT:core/Resources/Private/Templates/Email/',
        10 => 'EXT:backend/Resources/Private/Templates/Email/'
    ]
    ```

    List of paths to look for template files for templated emails. Should be
    specified as .txt and .html files.

-   **validators**

    -   *Type:* array
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['validators'\]
    -   *Default:* `[\Egulias\EmailValidator\Validation\RFCValidation::class]`

    List of validators used to validate an email address.

    Available validators are:

    -   `\Egulias\EmailValidator\Validation\DNSCheckValidation`
    -   `\Egulias\EmailValidator\Validation\NoRFCWarningsValidation`
    -   `\Egulias\EmailValidator\Validation\RFCValidation`
    -   `\Egulias\EmailValidator\Validation\SpoofCheckValidation`

    or by implementing a custom validator.

-   **transport**

    -   *Type:* text
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport'\]
    -   *Default:* 'sendmail'

    -   **smtp**

        Sends messages over the (standardized) Simple Message Transfer Protocol.
        It can deal with encryption and authentication. Most flexible option,
        requires a mail server and configurations in transport_smtp\_\* settings
        below. Works the same on Windows, Unix and MacOS.

    -   **sendmail**

        Sends messages by communicating with a locally installed MTA -
        such as sendmail. See setting transport_sendmail_command below.

    -   **dsn**

        Sends messages with the Symfony mailer, see
        [Symfony mailer documentation](https://symfony.com/doc/current/mailer.html).
        Configure this mailer with the [\[MAIL\]\[dsn\]](https://docs.typo3.org/permalink/t3coreapi:typo3confvars-mail-dsn@14.3)
        setting.

    -   **mbox**

        This does not send any mail out, but instead will write every outgoing mail
        to a file adhering to the RFC 4155 mbox format, which is a simple text
        file where the mails are concatenated. Useful for debugging the mail
        sending process and on development machines which cannot send mails to the
        outside. Configure the file to write to in the transport_mbox_file
        setting below

    -   ***classname***

        Custom class which implements
        `\Symfony\Component\Mailer\Transport\TransportInterface`. The constructor
        receives all settings from the MAIL section to make it possible to add
        custom settings.

-   **transport_smtp\_\***

    -   **transport_smtp_server**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_server'\]
        -   *Default:* 'localhost:25'

        *only with transport=smtp* server port of mail server to connect to. port
        defaults to "25".

    -   **transport_smtp_domain**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_domain'\]
        -   *Default:* ''

        Some smtp-relay-servers require the domain to be set from which the sender is
        sending an email. By default, the EsmtpTransport from Symfony will use the
        current domain/IP of the host or container. This will be sufficient for
        most servers, but some servers require that a valid domain is passed. If
        this isn't done, sending emails via such servers will fail.

        Setting a valid SMTP domain can be achieved by setting
        `transport_smtp_domain` in the `config/system/settings.php`.
        This will set the given domain to the EsmtpTransport agent and send the
        correct EHLO-command to the relay-server.

        **Configuration Example for GSuite:**

        **config/system/settings.php**

        ```php
        <?php

        return [
          // ...
          'MAIL' => [
            'defaultMailFromAddress' => 'webserver@example.org',
            'defaultMailFromName' => 'SYSTEMMAIL',
            'transport' => 'smtp',
            'transport_smtp_domain' => 'example.org',
            'transport_smtp_encrypt' => '',
            'transport_smtp_password' => '',
            'transport_smtp_server' => 'smtp-relay.gmail.com:587',
            'transport_smtp_username' => '',
          ],
          // ...
        ];

        ```

    -   **transport_smtp_stream_options**

        -   *Type:* array
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_stream_options'\]
        -   *Default:* null

        *only with transport=smtp* Sets additional stream options.

        Configuration Example:

        **config/system/settings.php**

        ```php
        <?php

        return [
          // ...
          'MAIL' => [
            'transport' => 'smtp',
            'transport_smtp_server' => 'localhost:1025',
            'transport_smtp_stream_options' => [
              'ssl' => [
                'verify_peer' => false,
                'verify_peer_name' => false,
              ],
            ],
          ],
          // ...
        ];

        ```

    -   **transport_smtp_encrypt**

        -   *Type:* bool
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_encrypt'\]
        -   *Default:* false

        *only with transport=smtp* Connects to the server using SSL/TLS
        (disables STARTTLS which is used by default if supported by the server).
        Must not be enabled when connecting to port 587, as servers will use
        STARTTLS (inner encryption) via SMTP instead of SMTPS. It will automatically
        be enabled if port is 465.

    -   **transport_smtp_username**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_username'\]
        -   *Default:* ''

        *only with transport=smtp* If your SMTP server requires authentication,
        enter your username here.

    -   **transport_smtp_password**

        -   *Type:* password
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_password'\]
        -   *Default:* ''

        *only with transport=smtp* If your SMTP server requires authentication,
        enter your password here.

    -   **transport_smtp_restart_threshold**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_restart_threshold'\]
        -   *Default:* ''

        *only with transport=smtp* Sets the maximum number of messages to send
        before re-starting the transport.

    -   **transport_smtp_restart_threshold_sleep**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_restart_threshold_sleep'\]
        -   *Default:* ''

        *only with transport=smtp* Sets the number of seconds to sleep
        between stopping and re-starting the transport.

    -   **transport_smtp_ping_threshold**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_smtp_ping_threshold'\]
        -   *Default:* ''

        *only with transport=smtp* Sets the minimum number of seconds required
        between two messages, before the server is pinged. If the transport
        wants to send a message and the time since the last message exceeds
        the specified threshold, the transport will ping the server first
        (NOOP command) to check if the connection is still alive. Otherwise the
        message will be sent without pinging the server first.

        > [!NOTE]
        > Do not set the threshold too low, as the SMTP server may drop the
        > connection if there are too many non-mail commands
        > (like pinging the server with NOOP).

-   **transport_sendmail\_\***

    -   **transport_sendmail_command**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_sendmail_command'\]
        -   *Default:* ''

        *only with transport=sendmail* The command to call to send a mail locally.

-   **transport_mbox\_\***

    -   **transport_mbox_file**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_mbox_file'\]
        -   *Default:* ''

        *only with transport=mbox* The file where to write the mails into.
        This file will be conforming the mbox format described in RFC 4155. It is
        a simple text file with a concatenation of all mails. Path must be absolute.

-   **transport_spool\_\***

    -   **transport_spool_type**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_spool_type'\]
        -   *Default:* ''

        -   **file**

            Messages get stored to the file system till they get sent through the
            command `mailer:spool:send`.

        -   **memory**

            Messages get sent at the end of the running process.

        -   ***classname***

            Custom class which implements the
            `\TYPO3\CMS\Core\Mail\DelayedTransportInterface` interface.

    -   **transport_spool_filepath**

        -   *Type:* text
        -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['transport_spool_filepath'\]
        -   *Default:* ''

        *only with transport_spool_type=file* Path where messages get temporarily
        stored. Ensure that this is stored outside of your webroot.

-   **dsn**

    -   *Type:* text
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['dsn'\]
    -   *Default:* ''

    *only with transport=dsn* The DSN configuration of the Symfony mailer
    (for example `smtp://userpass@smtp.example.org:25`). Symfony provides different
    mail transports like SMTP, sendmail or many 3rd party email providers like
    AWS SES, Gmail, MailChimp, Mailgun and more. You can find all supported
    providers in the
    [Symfony mailer documentation](https://symfony.com/doc/current/mailer.html).

    Set `[MAIL][dsn]` to the configuration value described in the
    Symfony mailer documentation (see above).

    Examples:

    -   `$GLOBALS['TYPO3_CONF_VARS']['MAIL']['dsn'] = "smtp://user:pass@smtp.example.org:25"`
    -   `$GLOBALS['TYPO3_CONF_VARS']['MAIL']['dsn'] = "sendmail://default"`

-   **defaultMailFromAddress**

    -   *Type:* text
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['defaultMailFromAddress'\]
    -   *Default:* ''

    This default email address is used when no other "from" address is
    set for a TYPO3-generated email. You can specify an email address only
    (for example `'info@example.org)'`.

-   **defaultMailFromName**

    -   *Type:* text
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['defaultMailFromName'\]
    -   *Default:* ''

    This default name is used when no other "from" name is set for a
    TYPO3-generated email.

-   **defaultMailReplyToAddress**

    -   *Type:* text
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['defaultMailReplyToAddress'\]
    -   *Default:* ''

    This default email address is used when no other "reply-to" address is set
    for a TYPO3-generated email. You can specify an email address only
    (for example `'info@example.org'`).

-   **defaultMailReplyToName**

    -   *Type:* text
    -   *Path:* $GLOBALS\['TYPO3_CONF_VARS'\]\['MAIL'\]\['defaultMailReplyToName'\]
    -   *Default:* ''

    This default name is used when no other "reply-to" name is set for a
    TYPO3-generated email.