Nextcloud needs outgoing mail for password resets, share notifications and activity digests. Out of the box it has no mail server to hand it to, so those emails silently never leave. Pointing it at an SMTP relay is one form in the admin settings — or a handful of keys in config.php if you manage the server from the command line.
| Setting | Value |
|---|---|
| SMTP host | smtp.postwing.app |
| Port | 587 |
| Encryption | STARTTLS (the connection is upgraded to TLS before login) |
| Username | The login of an SMTP token for your domain |
| Password | The password of that token — shown once, when the token is created |
Click your avatar → Administration settings → Basic settings and scroll to Email server:
| Field | Value |
|---|---|
| Send mode | SMTP |
| Encryption (Transport encryption in newer versions) | None/STARTTLS |
| From address | noreply @ your-domain.com — on your verified domain |
| Server address | smtp.postwing.app : 587 |
| Authentication | Enabled (authentication required) |
| Login | The login of an SMTP token for your domain |
| Password | That token's password |
465. SSL on 587 fails the handshake. The form writes to config/config.php. Note that mail_from_address is only the local part of the address:
<?php
// config/config.php — add these keys to the existing $CONFIG array
$CONFIG = array (
// ...
'mail_smtpmode' => 'smtp',
'mail_smtphost' => 'smtp.postwing.app',
'mail_smtpport' => 587,
'mail_smtpsecure' => '', // '' = STARTTLS when offered, 'ssl' = port 465
'mail_smtpauth' => true,
'mail_smtpname' => 'token-login@your-domain.com',
'mail_smtppassword' => 'your-token-password',
'mail_from_address' => 'noreply', // local part only
'mail_domain' => 'your-domain.com',
);The same keys can be set with occ:
# Run as the web server user from the Nextcloud directory
sudo -u www-data php occ config:system:set mail_smtpmode --value=smtp
sudo -u www-data php occ config:system:set mail_smtphost --value=smtp.postwing.app
sudo -u www-data php occ config:system:set mail_smtpport --value=587 --type=integer
sudo -u www-data php occ config:system:set mail_smtpsecure --value=""
sudo -u www-data php occ config:system:set mail_smtpauth --value=true --type=boolean
sudo -u www-data php occ config:system:set mail_smtpname --value=token-login@your-domain.com
sudo -u www-data php occ config:system:set mail_smtppassword --value=your-token-password
sudo -u www-data php occ config:system:set mail_from_address --value=noreply
sudo -u www-data php occ config:system:set mail_domain --value=your-domain.com The official nextcloud image writes the mail settings from environment variables when SMTP_HOST, MAIL_FROM_ADDRESS and MAIL_DOMAIN are all set. Leave SMTP_SECURE unset for port 587; for port 465 set it to ssl.
# docker-compose.yml — official nextcloud image
services:
app:
image: nextcloud
environment:
SMTP_HOST: smtp.postwing.app
SMTP_PORT: "587" # set it explicitly: the default is 25
SMTP_NAME: token-login@your-domain.com
SMTP_PASSWORD: your-token-password
MAIL_FROM_ADDRESS: noreply # local part only
MAIL_DOMAIN: your-domain.com The test goes to your own address, so first set one under Personal settings → Personal info. Then return to Email server and press the send email button. A failure shows the SMTP error; for more detail, set 'mail_smtpdebug' => true in config.php and read nextcloud.log with the log level lowered to debug.
| Error | Cause and fix |
|---|---|
| Connection could not be established | Outbound port blocked — use 8587 with None/STARTTLS or 8465 with SSL. |
Handshake or wrong version number error | Encryption set to SSL on port 587. Switch to None/STARTTLS. |
| Authentication failed (535) | Wrong token login or password, or authentication not enabled. |
| Sender address rejected | mail_domain is not your verified domain. |
| Form cannot be saved | config.php is not writable, or the Docker SMTP_* variables are in charge. |
| Test works, activity emails are late | Background jobs run in AJAX mode. Switch to system cron. |
Click your avatar → Administration settings → Basic settings, then scroll to the Email server section. The same values are stored in config/config.php as the mail_* keys, which is also where you edit them if the web form is read-only.
None/STARTTLS. Nextcloud has only two choices: None/STARTTLS, which upgrades the connection with STARTTLS whenever the server offers it, and SSL, which is implicit TLS for port 465. There is no separate STARTTLS option, so 'None' on port 587 is still an encrypted connection.
The test message goes to your own account's email address. Set it under Personal settings → Personal info first, then come back to the Email server section and send the test.
mail_from_address is only the part before the @ (for example noreply) and mail_domain is the part after it. Together they form the From address. Put the domain you verified in mail_domain, otherwise the message fails DKIM and SPF alignment.
Activity and notification digests are sent by background jobs, not at the moment of the event. If background jobs run in AJAX mode they only run while someone has Nextcloud open; switch to system cron under Basic settings → Background jobs.
Saving fails when config/config.php is not writable by the web server user, and the whole form is locked when config_is_read_only is set. In the official Docker image the SMTP_* variables are the source of the settings, so change them there and recreate the container.