OMERO.mail
==========

The OMERO server has the ability to send email to any users who have a properly
configured email address. OMERO system administrators can then use the
:omerocmd:`admin email` command to contact those users.

In order to activate the subsystem, minimally the :property:`omero.mail.config`
property will need to be activated.

Minimum configuration
---------------------

::

    $ bin/omero config set omero.mail.config true

By default, this will use "localhost" as the mail server on port 25 and send as
the user "omero". Likely you will need to configure OMERO to use your actual mail server.

For example,

::

    $ bin/omero config set omero.mail.host smtp.university.example

If authentication is required, then also configure:

::

    $ bin/omero config set omero.mail.username USER
    $ bin/omero config set omero.mail.password PASS

Setting email addresses
-----------------------

For the any user to receive email, a valid email address must be configured. By
default, the `root` OMERO user will *not* have an email address configured. This
can be done from one of the UIs or via the :omerocmd:`obj` command:

::

    $ bin/omero obj update Experimenter:0 email=root@university.example

.. note:: Using a mailing list or an alias for the `root` user can simplify configuration.

Enabling mail notifications
---------------------------

A number of "mail senders" are available for sending notifications of certain
events on the server. Those available include:

* `ServerUpMailSender` and `ServerDownMailSender` which mail when the server goes up or down
* `FailedLoginMailSender` which can be configured to send for particular users if a bad password is used
* `ObjectMailSender` which can be configured to send an email under various conditions. Instances which are configured include:
   * `newUserMailSender` which sends an email every time a user is created
   * `newCommentMailSender` which sends an email every time a user's image is commented on by another user.

To activate the senders, the :file:`etc/blitz/mail-senders.example` can be copied
to a file ending with ".xml".

OMERO.web error reporting
-------------------------

OMERO.web will email the users listed in the :property:`omero.web.admins`
whenever the application identify broken link (HTTP status code 404) or raises
an unhandled exception that results in an internal server error (HTTP status
code 500). This gives the administrators immediate notification of any errors.
The :property:`omero.web.admins` will get a description of the error,
a complete Python traceback, and details about the HTTP request that caused
the error.

.. note:: Reporting errors requires property :property:`omero.web.debug` set to
    `False` and works together with :ref:`omeroweb_error_handling`.

Other key properties
--------------------

Along with :property:`omero.mail.host`, a few general connection properties may
be needed for your particular SMTP server:

* :property:`omero.mail.port`
* :property:`omero.mail.smtp.auth`
* :property:`omero.mail.smtp.starttls.enable`
* :property:`omero.mail.from`

.. note:: :property:`omero.mail.from` may not be necessary but some
    servers may require it to match username. Regardless, it can be useful to
    inform users more clearly of who is getting in touch with them.

All properties can be found under the :ref:`mail_configuration` section of
:doc:`config`.

Further configuration
---------------------

Finally, if the above mail configuration properties do not cover your needs,
you can add your own implementation as described under |ExtendingOmero|. The
related property is :property:`omero.mail.bean`:

::

    $ bin/omero config set omero.mail.bean myMailImplementation