[[email-services]]
=== Configuring Watcher to Send Email
You can configure Watcher to send email from any SMTP email service. Email messages can contain
basic HTML tags. You can control which tags are allowed by   
<<email-html-sanitization, Configuring HTML Sanitization Options>>.

[[email-account]]
==== Configuring Email Accounts
You configure the accounts Watcher can use to send email in your `elasticsearch.yml` configuration file. 
Each account configuration has a unique name and specifies all of the SMTP information needed 
to send email from that account. You can also specify defaults for all emails that are sent through 
the account. For example, you can set defaults for the `from` and `bcc` fields to ensure that all 
emails are sent from the same address and always blind copied to the same address.

IMPORTANT:  If your email account is configured to require two step verification,
            you need to generate and use a unique App Password to send email from
            Watcher. Authentication will fail if you use your primary password.

If you configure multiple email accounts, you specify which account the email should be sent 
with in the <<actions-email, email>> action. If there is only one account configured, you 
do not have to specify the `account` attribute in the action definition. However, if you configure 
multiple accounts and omit the `account` attribute, there is no guarantee which account will be 
used to send the email.

To add an email account, set the `watcher.actions.email.service.account` property in 
`elasticsearch.yml`. See <<email-account-attributes, Email Account Attributes>> for the 
supported attributes. 

For example, the following snippet configures a single Gmail account named `work`. 

[source,yaml]
--------------------------------------------------
watcher.actions.email.service.account:
    work:
        profile: gmail
        email_defaults:
            from: 'John Doe <john.doe@host.domain>'
            bcc: archive@host.domain
        smtp:
            auth: true
            starttls.enable: true
            host: smtp.gmail.com
            port: 587
            user: <username>
            password: <password>
--------------------------------------------------

[[email-profile]]
The _email profile_ defines a strategy for building a MIME message. As with almost every standard 
out there, different email systems interpret the MIME standard differently and have slightly 
different ways of structuring MIME messages. Watcher provides three email profiles: `standard` 
(default), `gmail`, and `outlook`.

If you are using Gmail or Outlook, we recommend using the corresponding profile. Use the `standard` 
profile if you are using some other email system. For more information about configuring Watcher 
to work with different email systems, see:

* <<gmail, Sending Email from Gmail>>
* <<outlook, Sending Email from Outlook>>
* <<exchange, Sending Email from Exchange>>
* <<amazon-ses, Sending Email from Amazon SES>>

[[email-account-attributes]]
.Email Account Attributes
[options="header"]
|======
| Name                       | Required   | Default  | Description
| `profile`                  | no         | standard | The <<email-profile, profile>> to use to 
                                                       build the MIME messages that are sent from 
                                                       the account. Valid values: `standard` 
                                                       (default), `gmail` and `outlook`.
| `email_defaults.*`         | no         | -        | An optional set of email attributes to use 
                                                       as defaults for the emails sent from the 
                                                       account. See <<email-action-attributes, 
                                                       Email Action Attributes>> for the supported 
                                                       attributes. for the possible email 
                                                       attributes)
| `smtp.auth`                | no         | false    | When `true`, attempt to authenticate the 
                                                       user using the AUTH command.
| `smtp.host`                | yes        | -        | The SMTP server to connect to.
| `smtp.port`                | no         | 25       | The SMTP server port to connect to.
| `smtp.user`                | yes        | -        | The user name for SMTP.
| `smtp.password`            | no         | -        | The password for the specified SMTP user.
| `smtp.starttls.enable`     | no         | false    | When `true`, enables the use of the 
                                                       `STARTTLS` command (if supported by
                                                       the server) to switch the connection to a 
                                                       TLS-protected connection before issuing any 
                                                       login commands. Note that an appropriate 
                                                       trust store must configured so that the 
                                                       client will trust the server's certificate. 
                                                       Defaults to `false`.
| `smtp.*`                   | no         | -        | SMTP attributes that enable fine control 
                                                       over the SMTP protocol when sending messages. 
                                                       See https://javamail.java.net/nonav/docs/api/com/sun/mail/smtp/package-summary.html[com.sun.mail.smtp]
                                                       for the full list of SMTP properties you can 
                                                       set.
|======                                                       

[[gmail]]
===== Sending Email From Gmail

Use the following email account settings to send email from the https://mail.google.com[Gmail] 
SMTP service:

[source,yaml]
--------------------------------------------------
watcher.actions.email.service.account:
    gmail_account:
        profile: gmail
        smtp:
            auth: true
            starttls.enable: true
            host: smtp.gmail.com
            port: 587
            user: <username>
            password: <password>
--------------------------------------------------

If you get an authentication error that indicates that you need to continue the
sign-in process from a web browser when Watcher attempts to send email, you need
to configure Gmail to https://support.google.com/accounts/answer/6010255?hl=en[Allow Less 
Secure Apps to access your account]. 

If two-step verification is enabled for your account, you must generate and use
a unique App Password to send email from Watcher.See
https://support.google.com/accounts/answer/185833?hl=en[Sign in using App Passwords]
for more information.

[[outlook]]
===== Sending Email from Outlook.com

Use the following email account settings to send email action from the
https://www.outlook.com/[Outlook.com] SMTP service:

[source,yaml]
--------------------------------------------------
watcher.actions.email.service.account:
    outlook_account:
        profile: outlook
        smtp:
            auth: true
            starttls.enable: true
            host: smtp-mail.outlook.com
            port: 587
            user: <username>
            password: <password>
--------------------------------------------------

NOTE:   You need to use a unique App Password if two-step verification is enabled.
        See http://windows.microsoft.com/en-us/windows/app-passwords-two-step-verification[App 
        passwords and two-step verification] for more information.

[[amazon-ses]]
===== Sending Email from Amazon SES (Simple Email Service)

Use the following email account settings to send email from the 
http://aws.amazon.com/ses[Amazon Simple Email Service] (SES) SMTP service:

[source,yaml]
--------------------------------------------------
watcher.actions.email.service.account:
    ses_account:
        smtp:
            auth: true
            starttls.enable: true
            starttls.required: true
            host: email-smtp.us-east-1.amazonaws.com <1>
            port: 587
            user: <username>
            password: <password>
--------------------------------------------------

<1> `smtp.host` varies depending on the region

NOTE:   You need to use your Amazon SES SMTP credentials to send email through
        Amazon SES. For more information, see http://docs.aws.amazon.com/ses/latest/DeveloperGuide/smtp-credentials.html[Obtaining Your Amazon SES SMTP Credentials].

[[exchange]]
===== Sending Email from Microsoft Exchange

Use the following email account settings to send email action from Microsoft Exchange:

[source,yaml]
--------------------------------------------------
watcher.actions.email.service.account:
    exchange_account:
        profile: outlook
        email_defaults:
            from: <email address of service account> <1>
        smtp:
            auth: true
            starttls.enable: true
            host: <your exchange server>
            port: 587
            user: <email address of service account> <2>
            password: <password>
--------------------------------------------------

<1> Some organizations configure Exchange to validate that the `from` field is a
    valid local email account.
<2> Many organizations support use of your email address as your username, though
    it is a good idea to check with your system administrator if you receive
    authentication-related failures. 


// [[postfix]]
// ===== Sending Email from Postfix

// Use the following email account settings to send email from the http://www.postfix.org[Postfix] SMTP service:

// [source,yaml]
// --------------------------------------------------
// TODO
// --------------------------------------------------

[[email-html-sanitization]]
==== Configuring HTML Sanitization Options

The `email` action supports sending messages with an HTML body. However, for security reasons, 
Watcher https://en.wikipedia.org/wiki/HTML_sanitization[sanitizes] the HTML.

You can control which HTML features are allowed or disallowed by configuring the
`watcher.actions.email.html.sanitization.allow` and 
`watcher.actions.email.html.sanitization.disallow` settings in `elasticsearch.yml`. You can specify
individual HTML elements and the feature groups described in the following table. By default, 
Watcher allows the following features: `body`, `head`, `_tables`, `_links`, `_blocks`, `_formatting` 
and `img:embedded`.


[options="header"]
|======
| Name                       | Description

| `_tables`                  | All table related elements: `<table>`, `<th>`, `<tr>` and `<td>`.

| `_blocks`                  | The following block elements: `<p>`, `<div>`, `<h1>`, `<h2>`, `<h3>`,
                               `<h4>`, `<h5>`, `<h6>`, `<ul>`, `<ol>`, `<li>` and `<blockquote>`.

| `_formatting`              | The following inline formatting elements: `<b>`, `<i>`, `<s>`, `<u>`,
                               `<o>`, `<sup>`, `<sub>`, `<ins>`, `<del>`, `<strong>`, `<strike>`,
                               `<tt>`, `<code>`, `<big>`, `<small>`, `<br>`, `<span>` and `<em>`.

| `_links`                   | The `<a>` element with an `href` attribute that points to a URL using
                               the following protocols: `http`, `https` and `mailto`.

| `_styles`                  | The `style` attribute on all elements. Note that CSS attributes
                               are also sanitized to prevent XSS attacks.
                               
| `img` or `img:all`         | All images (external and embedded).

| `img:embedded`             | Only embedded images. Embedded images can only use the `cid:` URL
                               protocol in their `src` attribute.
|======

For example, the following settings allow the HTML to contain tables and block elements, but
disallow  `<h4>`, `<h5>` and `<h6>` tags.

[source,yaml]
--------------------------------------------------
watcher.actions.email.html.sanitization:
    allow: _tables, _blocks
    disallow: h4, h5, h6
--------------------------------------------------

To disable sanitization entirely, add the following setting to `elasticsearch.yml`:

[source,yaml]
--------------------------------------------------
watcher.actions.email.html.sanitization.enabled: false
--------------------------------------------------