Sending email #

owncloud.online sends email in several places: share invitations, password resets, new accounts, and calendar invitations. If email is not set up, these features fail, usually without a visible message. The error only shows up in the server log.

Run the occ commands on this page from the installation directory, for example after cd /var/www/owncloud.online.

What fails without email #

Two limitations that often surprise people:

• The core does not send a separate warning before a share expires. The expiration date is included in the invitation email (createMailBody() in lib/private/Share/MailNotifications.php). No reminder follows.
• Activity summaries are created by a background job of the activity app. Without a running cron they are never sent, see Background jobs (cron). To send them by hand:

sudo -u www-data php8.4 occ activity:send-emails

Setting up email in the web interface #

The Email server section is under Settings → Admin → General (settings/Panels/Admin/Mail.php, section general).

The upper form saves every change immediately (settings/js/panels/mail.js posts to /settings/admin/mailsettings on change). Username and password are saved separately, and only when you click the button. If you turn authentication off, MailSettingsController::setMailSettings() deletes the username and password from the configuration.

If config_is_read_only is true, both forms disappear. In their place you see "The config file is read only. Please adjust your setup by editing the config file manually." together with a note about syncing config.php in a cluster. You then have to edit config/config.php. The test field and the Send email button stay visible.

Setting up email in config.php #

A typical SMTP connection with STARTTLS on port 587:

sudo -u www-data php8.4 occ config:system:set mail_smtpmode --value smtp
sudo -u www-data php8.4 occ config:system:set mail_smtphost --value smtp.example.com
sudo -u www-data php8.4 occ config:system:set mail_smtpport --value 587 --type integer
sudo -u www-data php8.4 occ config:system:set mail_smtpsecure --value tls
sudo -u www-data php8.4 occ config:system:set mail_smtpauth --value true --type boolean
sudo -u www-data php8.4 occ config:system:set mail_smtpauthtype --value LOGIN
sudo -u www-data php8.4 occ config:system:set mail_smtpname --value noreply@example.com
sudo -u www-data php8.4 occ config:system:set mail_smtppassword --value 'CHANGE_ME'
sudo -u www-data php8.4 occ config:system:set mail_from_address --value noreply
sudo -u www-data php8.4 occ config:system:set mail_domain --value example.com

--type is required for mail_smtpport and mail_smtpauth. Otherwise the values end up in the file as strings. Editing config/config.php directly has the same effect:

'mail_smtpmode' => 'smtp',
'mail_smtphost' => 'smtp.example.com',
'mail_smtpport' => 587,
'mail_smtpsecure' => 'tls',
'mail_smtpauth' => true,
'mail_smtpauthtype' => 'LOGIN',
'mail_smtpname' => 'noreply@example.com',
'mail_smtppassword' => 'CHANGE_ME',
'mail_from_address' => 'noreply',
'mail_domain' => 'example.com',

Checking a value:

sudo -u www-data php8.4 occ config:system:get mail_smtphost

occ config:list system hides mail_smtphost, mail_smtpname, mail_smtppassword, mail_from_address, and mail_domain because lib/private/SystemConfig.php marks them as sensitive. config:system:get and config:list system --private print them in plain text.

All mail_ keys #

Send modes in detail (Mailer::getInstance() and Mailer::getSendMailInstance()):

• smtp: connects to mail_smtphost:mail_smtpport. After 100 messages the connection is reopened.
• qmail: calls /var/qmail/bin/sendmail -bs.
• php, sendmail, and any other value: calls /usr/sbin/sendmail -bs. So php mode does not use the mail() function and does not use the sendmail_path from php.ini, even though the description in config/config.sample.php suggests it. Without a local mail server (MTA), this fails.

Two more keys without the mail_ prefix belong here:

From address and reply-to address #

\OCP\Util::getDefaultEmailAddress() builds the sender address. Each part of the code sets a default local part, which mail_from_address overrides:

The domain part comes from mail_domain, or from the server's host name if mail_domain is not set. If the result is not a valid address, the code falls back to <localpart>@localhost.localdomain. Most receiving servers reject such emails. On production systems, always set mail_from_address and mail_domain explicitly, to a domain your SMTP server is allowed to send for.

The reply-to address is only set for share emails (MailNotifications::getReplyTo()). It is the address of the user who shared. If that user has no address, the default sender address with the local part sharing-noreply is used, so mail_from_address applies here too if it is set. Calendar invitations are a special case: IMipPlugin uses the sender of the iTIP message (the organizer or a replying attendee, depending on the method) as both sender and reply-to address. mail_from_address does not apply there. All other emails have no reply-to address of their own.

Test email #

At the bottom of the Email server section you find the Test receiver email field, prefilled with the address of the logged-in account, and the Send email button. Results:

• Success: "Email sent".
• Error: "A problem occurred while sending the email. Please revise your settings. (Error: …)". The parentheses contain the message from the transport, see Troubleshooting.
• If the field is empty (this happens when your own account has no address), settings/js/panels/mail.js stops right away and shows the hard-coded message "Please provide an test receiver email". Nothing is sent.

The test email goes out with the default local part no-reply (so no-reply@<mail_domain> unless mail_from_address is set) and the subject "test email settings". It only tests the path from the server to the mail server, not whether share and password emails will be delivered later.

Setting or adding user addresses:

# set the address of an existing account
sudo -u www-data php8.4 occ user:modify username email person@example.com

# create an account with an address
sudo -u www-data php8.4 occ user:add --email person@example.com username

Users maintain their own address under Settings → Personal → General in the Email section.

Logging the SMTP dialog #

For troubleshooting you can log the whole SMTP dialog. This also logs the username, so only turn it on briefly:

sudo -u www-data php8.4 occ config:system:set mail_smtpdebug --value true --type boolean
sudo -u www-data php8.4 occ config:system:set loglevel --value 0 --type integer

loglevel 0 is needed because the transport writes at debug level. Afterwards, reset both (loglevel to 2, mail_smtpdebug to false). For reading the log, see Server log and error messages.

Troubleshooting #

If the cause is still unclear, log the SMTP dialog as described above. It contains the mail server's answer in plain text.