History

Nick Satterly 2a6632b78f Fix multiple linting errors		2023-03-21 00:15:34 +01:00
..
README.md	feat: mailer pickable sevs (#336 )	2021-01-06 23:18:29 +01:00
email.html.tmpl	Fix multiple linting errors	2023-03-21 00:15:34 +01:00
email.tmpl	Fix multiple linting errors	2023-03-21 00:15:34 +01:00
mailer.py	Fix multiple linting errors	2023-03-21 00:15:34 +01:00
requirements.txt	Fix multiple linting errors	2023-03-21 00:15:34 +01:00
setup.cfg	Move email rules to more flexible JSON format	2016-05-12 23:47:02 -03:00
setup.py	Fix multiple linting errors	2023-03-21 00:15:34 +01:00
test_rules.py	Fix multiple linting errors	2023-03-21 00:15:34 +01:00

README.md

Mailer Integration

Send emails for alerts received by Alerta.

For help, join

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 by default
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  ; must have "write:heartbeats" scope
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_username = alt.email@gmail.com
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.

You can also set an alternate SMTP username for authenticating against the email server if it differs from the 'mail_from' address. This is required when using an email delivery service like sendgrid.

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_USERNAME - can be used instead of smtp_username in the configuration file, defaults to the value set for the mail_from field. 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 for more info.

Testing

To execute unit-tests run:

$ python setup.py test