Email Configuration

Introduction

ownCloud is capable of sending emails for a range of reasons. These include:

  • Password reset emails

  • Notifying users of new file shares

  • Changes in files

  • Activity notifications

To make use of them, users need to configure which notifications they want to receive. They can do this on their Personal pages.

To be able to send emails, a functioning mail server must be available, whether locally in your network, or remotely.

The Graphical Email Configuration Wizard

The wizard supports two mail server types: SMTP and PHP. Use SMTP for a remote email server, and PHP when your mail server is on the same machine as ownCloud.

In most cases the smtp option is best, because it removes the extra step of passing through PHP, and you can control all of your mail server options in one place, in your ownCloud’s email server configuration.

Configuring an SMTP Server

To configure ownCloud to interact with an SMTP server, you can either update config/config.php by hand, or use the Graphical Email Configuration Wizard, which updates config/config.php for you.

You need the following information from your email server administrator to connect ownCloud to a remote SMTP server:

  • Encryption type: None, SSL/TLS or STARTTLS.

  • The From address you want your outgoing ownCloud mails to use.

  • Whether authentication is required.

  • Authentication method: None, Login, Plain, or NT LAN Manager.

  • The server’s IP address or fully-qualified domain name (FQDN).

  • Login credentials, if required.

image

Your changes are saved immediately.

You must enter a valid email address to which a test email will be sent. This field is mandatory and will be prefilled with the logged-in admin’s email if set, but can be changed to any other valid email address. Note that this test recipient address can’t be set via a config value in config.php. Click the Send Email button to test your configuration. This sends a test message to the email address you configured. The test message says:

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

--
ownCloud
web services under your control

Configuring PHP for sending Emails

To configure PHP select it and enter your desired return address.

image

Same as with the SMTP configuration above, you must enter an email address to which a test email will be sent when testing the configuration. For details see the section above.

PHP mode uses your local sendmail binary and any drop-in Sendmail replacement such as Postfix, Exim, or Courier. All of these include a sendmail binary, and are freely interchangeable. Use this if you want to use php.ini to control some of your mail server functions, such as setting paths, headers, or passing extra command options to the sendmail binary. These vary depending on which server you are using, so consult your server’s documentation to see what your options are.

Setting Mail Server Parameters via config.php

If you prefer, you may set your email server parameters directly in config/config.php.

Supported SMTP sending modes

Compatibility of sending modes might depend on the installation environment. In case of problems with a sending mode, it is recommended to try other mode configurations.

SMTP

If you want to send email using a local or remote SMTP server it is necessary to enter the name or IP address of the server, optionally followed by a colon and port number, e.g. :425. If this value is not given the default port 25/tcp will be used unless you change that by modifying the mail_smtpport parameter. Multiple servers can be entered, separated by semicolons:

'mail_smtpmode'     => 'smtp',
'mail_smtphost'     => 'smtp-1.server.dom;smtp-2.server.dom:425',
'mail_smtpport'     => 25,

Or:

'mail_smtpmode'     => 'smtp',
'mail_smtphost'     => 'smtp.server.dom',
'mail_smtpport'     => 425,

If a malware or SPAM scanner is running on the SMTP server it might be necessary that you increase the SMTP timeout to e.g., 30s:

'mail_smtptimeout'  => 30,

If the SMTP server accepts insecure connections, the default setting can be used:

'mail_smtpsecure'   => '',

If the SMTP server only accepts secure connections you can choose between the following two variants:

SSL/TLS

A secure connection will be initiated using SSL/TLS via SMTPS on the default port 465/tcp:

'mail_smtphost'     => 'smtp.server.dom:465',
'mail_smtpsecure'   => 'ssl',
STARTTLS

A secure connection will be initiated using STARTTLS via SMTP on the default port 25/tcp:

'mail_smtphost'     => 'smtp.server.dom',
'mail_smtpsecure'   => 'tls',

An alternative is the port 587/tcp (recommended):

'mail_smtphost'     => 'smtp.server.dom:587',
'mail_smtpsecure'   => 'tls',
Authentication

And finally it is necessary to configure if the SMTP server requires authentication, if not, the default values can be taken as is.

'mail_smtpauth'     => false,
'mail_smtpname'     => '',
'mail_smtppassword' => '',

If SMTP authentication is required you have to set the required username and password and can optionally choose between the authentication types LOGIN (default) or PLAIN.

'mail_smtpauth'     => true,
'mail_smtpauthtype' => 'LOGIN',
'mail_smtpname'     => 'username',
'mail_smtppassword' => 'password',

PHP Mail

If you want to use PHP mail it is necessary to have an installed and working email system on your server. Which program in detail is used to send email is defined by the configuration settings in the php.ini file. On *nix systems this will most likely be Sendmail. ownCloud should be able to send email out of the box.

'mail_smtpmode'     => 'php',
'mail_smtphost'     => '127.0.0.1',
'mail_smtpport'     => 25,
'mail_smtptimeout'  => 10,
'mail_smtpsecure'   => '',
'mail_smtpauth'     => false,
'mail_smtpauthtype' => 'LOGIN',
'mail_smtpname'     => '',
'mail_smtppassword' => '',

Send a Test Email

Regardless of how you have configured ownCloud to interact with an email server, to test your email configuration, save your email address in your personal settings and then use the Send email button in the Email Server section of the Admin settings page.

Using Self-Signed Certificates

When using self-signed certificates on the remote SMTP server, the certificate must be imported into ownCloud. Please refer to Importing System-wide and Personal SSL Certificates for more information.

Troubleshooting

If you are unable to send email, try turning on debugging. Do this by enabling the mail_smtpdebug parameter in config/config.php.

'mail_smtpdebug' => true,
Immediately after pressing the Send email button, as described before, several SMTP → get_lines(): … messages appear on the screen. This is expected behavior and can be ignored.

Why is my web domain different from my mail domain?

The default domain name used for the sender address is the hostname where your ownCloud installation is served. If you have a different mail domain name you can override this behavior by setting the following configuration parameter:

'mail_domain' => 'example.com',

This setting results in every email sent by ownCloud (for example, the password reset email) having the domain part of the sender address appear as follows

no-reply@example.com

How can I find out if an SMTP server is reachable?

Use the ping command to check the server availability

ping smtp.server.dom
PING smtp.server.dom (ip-address) 56(84) bytes of data.
64 bytes from your-server.local.lan (192.168.1.10): icmp_req=1 ttl=64 time=3.64ms

How can I find out if the SMTP server is listening on a specific TCP port?

The best way to get mail server information is to ask your mail server admin. If you are the mail server admin, or need information in a hurry, you can use the netstat command. This example shows all active servers on your system, and the ports they are listening on. The SMTP server is listening on localhost port 25.

netstat -pant
Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address   Foreign Address  State  ID/Program name
tcp    0      0    0.0.0.0:631     0.0.0.0:*        LISTEN   4418/cupsd
tcp    0      0    127.0.0.1:25    0.0.0.0:*        LISTEN   2245/exim4
tcp    0      0    127.0.0.1:3306  0.0.0.0:*        LISTEN   1524/mysqld
  • 25/tcp is unencrypted smtp

  • 110/tcp/udp is unencrypted pop3

  • 143/tcp/udp is unencrypted imap4

  • 465/tcp is encrypted smtps

  • 993/tcp/udp is encrypted imaps

  • 995/tcp/udp is encrypted pop3s

How can I determine if the SMTP server supports SMTPS?

A good indication that the SMTP server supports SMTPS is that it is listening on port 465.

How can I determine what authorization and encryption protocols the mail server supports?

SMTP servers usually announce the availability of STARTTLS immediately after a connection has been established. You can easily check this using the telnet command.

You must enter the marked lines to obtain the information displayed.
telnet smtp.domain.dom 25
Trying 192.168.1.10...
Connected to smtp.domain.dom.
Escape character is '^]'.
220 smtp.domain.dom ESMTP Exim 4.80.1 Tue, 22 Jan 2013 22:39:55 +0100
EHLO your-server.local.lan                   # <<< enter this command
250-smtp.domain.dom Hello your-server.local.lan [ip-address]
250-SIZE 52428800
250-8BITMIME
250-PIPELINING
250-AUTH PLAIN LOGIN CRAM-MD5                 # <<< Supported auth protocols
250-STARTTLS                                  # <<< Encryption is supported
250 HELP
QUIT                                          # <<< enter this command
221 smtp.domain.dom closing connection
Connection closed by foreign host.

Enabling Debug Mode

If you are unable to send email, it might be useful to activate further debug messages by enabling the mail_smtpdebug parameter:

'mail_smtpdebug' => true,
Immediately after pressing the Send email button, as described before, several SMTP → get_lines(): … messages appear on the screen. This is expected behavior and can be ignored.

Using Email Templates

You have to install and enable a custom theme in order to use and customize email templates.

Most emails sent from ownCloud are based on editable email templates, which are a mixture of PHP and HTML. The currently available templates are:

Email Format Description File Location

Activity notification mail

plain text

Notification of activities that users have enabled in the Notifications section of their Personal pages.

core/templates/mail.php

Lost password mail

HTML

Password reset email for users who lose their passwords.

core/templates/lostpassword/email.php

New user email

HTML

settings/templates/email.new_user.php

plain text

settings/templates/email.new_user_plain_text.php

Public link share email

HTML

Notify users of new public link shares.

core/templates/mail.php

plain text

core/templates/altmail.php

New file share email

HTML

Notify users of new file shares.

core/templates/internalmail.php

plain text

core/templates/internalaltmail.php

The templates are written in PHP and HTML, and are already loaded with the relevant variables such as username, share links, and filenames. You can, if you are careful, edit these — even without knowing PHP or HTML. Don’t touch any of the code, but it’s OK to edit the text portions of the messages.

For example, this the lost password mail template:

<?php

echo str_replace(
    '{link}',
    $_['link'],
    $l->t('Use the following link to reset your password: {link}')
);

You could change the text portion of the template, Use the following link to reset your password: to say something else, such as:

Click the following link to reset your password.
If you did not ask for a password reset, ignore this message.

Again, be very careful to change nothing but the message text, because the tiniest coding error will break the template.