SMTP for TYPO3 — site mail that arrives
TYPO3 sends its mail through the transport defined in the installation settings. By default that is the server's local mail function — without authentication and without reputation, which is why form submissions and password reset emails regularly end up as spam at Gmail and Outlook.
TYPO3 can set that transport directly to SMTP, without an extra extension. You enter server, port, encryption and login in the installation's MAIL settings, and everything TYPO3 sends — including form and workflow mail from extensions — goes through your relay from then on.
Why it goes wrong without a relay
TYPO3 is used for large, multilingual sites of companies and public bodies, often with forms that start a real process: a registration, a quote request, a job application. If the confirmation fails to arrive, the applicant calls — or fills in the form again and you end up with duplicate records. The mail does leave, but nothing proves it comes from your domain.
Setting up SMTP in TYPO3
Collect your details
Log in to your 2mail account and retrieve your SMTP server, username and password there.
Fill them in inside TYPO3
TYPO3's mail configuration lives in the installation settings, under the MAIL keys. Set the transport to SMTP, enter the server together with the port, choose the encryption and provide username and password. Also set the default sender address and sender name to your own domain. The install tool has a test email — send it to an external address at a major provider.
Authenticate your domain
Make sure SPF, DKIM and DMARC are set correctly for your domain, so recipients can verify that the mail comes from you.
Test
From your platform, send a test message to an address at a major provider and check that it arrives in the inbox and not in the spam folder.
The fields TYPO3 asks for
Every platform names them slightly differently, but it is always the same five. The actual values are tied to your account and can be found in your 2mail account — take them from there, so you are sure to use the right ones.
| Field | What you enter |
|---|---|
| SMTP server (host) | The server name from your 2mail account. |
| Port | The port that matches your chosen encryption; your account shows which one. |
| Encryption | TLS. Never send unencrypted — your credentials would otherwise travel in plain text. |
| Username | The SMTP login of your 2mail account. |
| Password | The matching password. Never use the password of an employee's mailbox. |
SMTP configuration for TYPO3 in code
Working examples for port 587 with STARTTLS, ready to copy. Replace the sender address with an address on your own domain and check the server name and login in your 2mail account. The password belongs in an environment variable — never in the code and never in version control.
The MAIL settings in additional.php
Put the SMTP details in the additional configuration file rather than in settings.php: the latter is rewritten by the install tool, and a getenv() call does not survive that. This way login and password come from the server's environment variables and stay out of version control. Mind transport_smtp_encrypt: in current TYPO3 versions it is a boolean that must be false on port 587 — STARTTLS then happens automatically. Only very old versions (up to and including 9) expected the string tls here.
<?php
// config/system/additional.php
// (older installations: typo3conf/AdditionalConfiguration.php)
$GLOBALS['TYPO3_CONF_VARS']['MAIL'] = array_replace(
$GLOBALS['TYPO3_CONF_VARS']['MAIL'],
[
'transport' => 'smtp',
'transport_smtp_server' => 'relay.2mail.eu:587', // host AND port, in one value
'transport_smtp_encrypt' => false, // false on 587 = STARTTLS; true = TLS from the first byte (465)
'transport_smtp_username' => getenv('SMTP_USERNAME'),
'transport_smtp_password' => getenv('SMTP_PASSWORD'),
'defaultMailFromAddress' => 'noreply@example.com',
'defaultMailFromName' => 'Example',
]
);Test email: install tool or MailMessage
The quickest check is in the backend: Admin Tools → Environment → Test Mail Setup sends a message with exactly the settings that are actually in effect. If you want to test from your own extension, TYPO3's MailMessage class is all you need — the same route that forms and workflow emails take.
use TYPO3\CMS\Core\Mail\MailMessage;
use TYPO3\CMS\Core\Utility\GeneralUtility;
// No from(): TYPO3 falls back to defaultMailFromAddress / defaultMailFromName.
$mail = GeneralUtility::makeInstance(MailMessage::class);
$mail
->to('you@example.org')
->subject('SMTP test')
->text('Sent through the 2mail SMTP relay.')
->send();Which emails TYPO3 sends
As soon as the relay is set up, all of these run through 2mail — you do not have to configure them one by one.
Pitfalls with TYPO3
Settings in the wrong layer
TYPO3 reads the installation settings from several layers: the system configuration file and an additional file that overrides it. If you put the SMTP details in one layer while the other still holds the old transport, the latter wins. Check in the install tool which value is actually in effect.
Server and port belong together
TYPO3 expects server and port together in the transport setting. If you leave out the port, TYPO3 falls back to a default that does not match your encryption — and the connection hangs or is cut off immediately. Port 587 with STARTTLS is the safe choice.
Staging with the same details
If the configuration is deployed through version control, a test or staging environment sends with the same login — to real addresses from a copied database. Use a separate login per environment, so you can shut the test environment off on its own.
Common error messages with TYPO3
The messages you get when host, port, encryption or login are wrong — quoted literally, so you recognise them in your log, with the cause and the fix next to them.
| Message | Cause | Fix |
|---|---|---|
Connection could not be established with host "relay.2mail.eu:25": stream_socket_client(): Unable to connect to relay.2mail.eu:25 (Connection timed out) | transport_smtp_server holds only the server name, without a port. TYPO3 then falls back to port 25, which most hosts and cloud platforms block for outbound traffic. | Write server and port together in one value: relay.2mail.eu:587. |
Connection could not be established with host "ssl://relay.2mail.eu:587": stream_socket_client(): SSL operation failed with code 1. OpenSSL Error messages: error:…:SSL routines::wrong version number | transport_smtp_encrypt is set to true. TYPO3 then expects TLS from the first byte, whereas port 587 starts in plain text and only upgrades afterwards through STARTTLS. | Set transport_smtp_encrypt to false and keep the port at 587. The connection is still encrypted. |
Failed to authenticate on SMTP server with username "…" using the following authenticators: "LOGIN", "PLAIN". … Expected response code "235" but got code "535" | The relay rejects the login. Either the username or password is wrong, or the environment variable is empty in the context PHP runs in — the web server does not automatically see the same variables as your shell. | Check that getenv('SMTP_PASSWORD') returns a value inside the web server, and use the SMTP login from your 2mail account — not the password of a mailbox. |
Expected response code "250/251/252" but got code "554", with message "554 5.7.1 <noreply@example.com>: Sender address rejected" | The login is fine, but the sender address is on a domain that is not linked to your 2mail account. Often defaultMailFromAddress is empty, or a form sets its own sender. | Set defaultMailFromAddress to an address on a domain you have added in 2mail, and check per form which sender address it uses. |
A different platform?
SMTP is a standard protocol: any system that speaks SMTP — a CRM, an ERP, a custom application or a server — can send through 2mail using the same five fields.