How to configure SMTP in Nextcloud

Nextcloud sends password reset links, share notifications, activity notices, and other user-facing messages through an external mail service. Connecting the instance to an SMTP relay gives those messages a sender address that belongs to the organization and avoids relying on a local sendmail binary or disabled mail delivery.

Mail settings are stored in config.php and can be written through occ from the server shell. The same values can also be saved from the Email server section in the web admin settings, where the Send email button performs the final delivery test.

Authenticated submission on port 587 normally uses None/STARTTLS in Nextcloud, because recent releases upgrade automatically when the relay advertises STARTTLS. Use ssl with port 465 only for implicit SMTPS, and keep relay passwords out of saved transcripts, tickets, and screenshots.

1. Gather the relay settings from the mail administrator.

   SMTP host: smtp.mail.example
   Port: 587
   Encryption: None/STARTTLS
   Authentication: required
   SMTP username: cloud-notify@example.com
   Sender address: noreply@example.com

   Use a relay account, app password, or provider-issued SMTP credential that is allowed to send as the selected sender address.

2. Open a shell in the Nextcloud installation directory.

   $ cd /var/www/nextcloud

   Use the directory that contains the occ file. On Debian and Ubuntu web-server installs, the web user is usually www-data.
   Related: How to run Nextcloud occ commands

3. Set the sender local part.

   $ sudo -E -u www-data php occ config:system:set mail_from_address --value="noreply"
   System config value mail_from_address set to noreply

4. Set the sender domain.

   $ sudo -E -u www-data php occ config:system:set mail_domain --value="example.com"
   System config value mail_domain set to example.com

   Nextcloud combines mail_from_address and mail_domain into the visible sender address, such as noreply@example.com.

5. Enable SMTP delivery mode.

   $ sudo -E -u www-data php occ config:system:set mail_smtpmode --value="smtp"
   System config value mail_smtpmode set to smtp

6. Set the SMTP relay host.

   $ sudo -E -u www-data php occ config:system:set mail_smtphost --value="smtp.mail.example"
   System config value mail_smtphost set to smtp.mail.example

7. Set the SMTP relay port as an integer.

   $ sudo -E -u www-data php occ config:system:set mail_smtpport --value=587 --type=integer
   System config value mail_smtpport set to integer 587

   For implicit SMTPS, use port 465 and set mail_smtpsecure to ssl in the next step.

8. Allow automatic STARTTLS for a submission relay.

   $ sudo -E -u www-data php occ config:system:set mail_smtpsecure --value=""
   System config value mail_smtpsecure set to 

   An empty mail_smtpsecure value maps to None/STARTTLS. Current Nextcloud releases use STARTTLS automatically when the relay supports it.

9. Enable SMTP authentication.

   $ sudo -E -u www-data php occ config:system:set mail_smtpauth --value=true --type=boolean
   System config value mail_smtpauth set to boolean true

   For a trusted internal relay that does not require authentication, set this value to false and leave mail_smtpname and mail_smtppassword empty.

10. Set the SMTP username.

    $ sudo -E -u www-data php occ config:system:set mail_smtpname --value="cloud-notify@example.com"
    System config value mail_smtpname set to cloud-notify@example.com

11. Set the SMTP password.

    $ sudo -E -u www-data php occ config:system:set mail_smtppassword --value="provider-issued-app-password"

    The password can be visible in shell history, process listings, or terminal logs while the command runs. Use a dedicated relay credential and rotate it if it is exposed.

12. Check the saved relay host without printing the password.

    $ sudo -E -u www-data php occ config:system:get mail_smtphost
    smtp.mail.example

13. Send a test message from the web admin settings.

    Sign in as an administrator, open Settings → Administration → Basic settings, find Email server, and click Send email. The recipient should receive a message that says the settings seem to be correct.

14. Check the Nextcloud log if the test message fails.

    $ sudo -E -u www-data php occ log:tail 5
     --------- ------------- --------------------- --------------------------- 
      Level     App           Message               Time                       
     --------- ------------- --------------------- --------------------------- 
      Error     mail          Failed to connect      2026-06-29T08:10:42+00:00  
                              to SMTP host                                    
                                                                               
     --------- ------------- --------------------- --------------------------- 

    Use the log entry to separate relay reachability, authentication, sender-policy, and TLS problems before changing unrelated mail settings.
    Related: How to view Nextcloud logs

15. Confirm that the recipient received the Nextcloud test message.

    If you received this email, the settings seem to be correct.