alerta_alerta-contrib/integrations/mailer/README.md

Mailer Integration
==================

Send emails for alerts received by Alerta.

For help, join [![Gitter chat](https://badges.gitter.im/alerta/chat.png)](https://gitter.im/alerta/chat)

Overview
--------

It is specifically designed to reduce the number of unnecessary emails by
ensuring that alerts meet the following criteria:

  * must not be a duplicate alert (ie. ``repeat != True``)
  * must have status of ``open`` or ``closed``
  * must have a current severity *OR* previous severity of ``critical`` or ``major``
  * must not have been cleared down within 30 seconds (to prevent flapping alerts spamming)

To achieve the above, alerts are actually held for a minimum of 30 seconds
before they generate emails.

Installation
------------

Clone the GitHub repo and run:

    $ python setup.py install

Or, to install remotely from GitHub run:

    $ pip install git+https://github.com/alerta/alerta-contrib.git#subdirectory=integrations/mailer

Configuration
-------------

Settings are changed using an ini-style configuration file that is also
used for the ``alerta`` cli.

A section called ``[alerta-mailer]`` is used to clearly define which
settings apply to the mailer script.

```
[alerta-mailer]
key = demo-key
mail_to = john.doe@gmail.com,jane.doe@gmail.com
mail_from = your.email@gmail.com
amqp_url = redis://localhost:6379/
dashboard_url = http://localhost:8000
smtp_password = okvqhitqomebufyv
smtp_use_ssl = False
debug = True
skip_mta = False
email_type = text
```

If you are using Google Gmail as the SMTP server. You will need to create
an application-specific password.

You can skip the use of an SMTP server using the option 'skip_mta'. Note
that in most cases is recommended to use an SMTP outbound server as the
MTA, but if you know what you're doing you can use skip_mta and then
``alerta-mailer`` will resolve the proper destination MX DNS record for
each address and attempt to deliver the email directly. Some email
systems may detect certain email patterns to black-list you, such as
sending email using a hostname such as 'localhost'. You may need to
set the 'mail_localhost' option or set a proper FQDN in your server to
avoid this.

You can also use IP-authentication in your own SMTP server (by only
white-listing the alerta server IP), in such cases you should not
set the 'smtp_password' option to skip authentication altogether.

Application-specific passwords
https://support.google.com/accounts/answer/185833?hl=en

Rules File
----------

Notifications to other emails according regexp criteria can be enabled,
creating a JSON formatted file under ```alerta.rules.d/``` with the
following format:

```
[
    {
        "name": "foo",
        "fields": [
            {"field": "resource", "regex": "db-\w+"}
        ],
        "contacts": ["dba@lists.mycompany.com", "dev@lists.mycompany.com"]
    },
    {
        "name": "bar",
        "fields": [
            {"field": "resource", "regex": "web-\w+"}
        ],
        "contacts": ["dev@lists.mycompany.com"],
        "exclude" : true
    }
]
```

``field`` is a reference to the alert object, regex is a valid python
regexp and contacts are a list of mails who will receive an e-mail if
the regular expression matches.

Multiple ``field`` dictionary can be supplied and all ``regex`` must
match for the email to be sent.

If the ``exclude`` parameter is set, contact list will be cleared and
replaced with only the contacts of the current matched rule.

Environment Variables
---------------------

``SMTP_PASSWORD`` - can be used instead of smtp_password in the configuration file.

Email Format
------------

The format for emails uses a templating engine called Jinja2.

The variable email_type can have 2 possible values:

- html: for just html emails, will fallback to text for text clients (mutt, etc)
- text: for just plain text emails

Multiple files config support
-----------------------------

Multiple configs files are supported for alerta-mailer you just need
to create a directory with the name of the config file with the ``.d``
suffix, i.e: (assuming you have a config file called ``mailer.conf``
on ``/etc/alerta/`` you will need to create the directory ``mailer.conf.d``
at the same level of your config file (mailer.conf in this example),
and place all your configs there.

Multiple email rules files can be supplied as well and rules are
going to be applied top-down as they appear on the filesystem and
on the files themselves.

Deployment
----------

    $ export SMTP_PASSWORD=okvqhitqomebufyv
    $ alerta-mailer

Dependencies
------------

The Alerta server *MUST* have the AMQP plugin enabled and configured.
See [AMQP](plugins/amqp) for more info.

Testing
-------

To execute unit-tests run:

    $ python setup.py test

License
-------

Copyright (c) 2015-2016 Nick Satterly and [AUTHORS](AUTHORS). Available under the MIT License.