Watcher email action

Watcher email action

Use the email action to send email notifications. To send email, you must configure at least one email account in elasticsearch.yml.

Email notifications can be plain text or styled using HTML. You can include information from the watch execution payload using templates and attach the entire watch payload to the message.

See Email action attributes for the supported attributes. Any attributes that are missing from the email action definition are looked up in the email account configuration. The required attributes must either be set in the email action definition or the account’s email_defaults.

Configuring email actions

You configure email actions in the actions array. Action-specific attributes are specified using the email keyword.

For example, the following email action uses a template to include data from the watch payload in the email body:

"actions" : {
  "send_email" : { 
    "email" : { 
      "to" : "username@example.org", 
      "subject" : "Watcher Notification", 
      "body" : "{{ctx.payload.hits.total}} error logs found" 
    }
  }
}

Configuring email attachments

You can attach the execution context payload or data from an any HTTP service to the email notification. There is no limit on the number of attachments you can configure.

To configure attachments, specify a name for the attached file and the type of attachment: data, http or reporting. The data attachment type attaches the execution context payload to the email message. The http attachment type enables you to issue an HTTP request and attach the response to the email message. When configuring the http attachment type, you must specify the request URL. The reporting attachment type is a special type to include PDF rendered dashboards from kibana. This type is consistently polling the kibana app if the dashboard rendering is done, preventing long running HTTP connections, that are potentially killed by firewalls or load balancers in-between.

"actions" : {
  "email_admin" : {
    "email": {
      "to": "John Doe <john.doe@example.com>",
      "attachments" : {
        "my_image.png" : { 
          "http" : { 
            "content_type" : "image/png",
            "request" : {
              "url": "http://example.org/foo/my-image.png" 
            }
          }
        },
        "dashboard.pdf" : {
          "reporting" : {
            "url": "http://example.org:5601/api/reporting/generate/dashboard/Error-Monitoring"
          }
        },
        "data.yml" : {
          "data" : {
            "format" : "yaml" 
          }
        }
      }
    }
  }
}

Table 85. http attachment type attributes

Table 86. data attachment type attributes

Table 87. reporting attachment type attributes

Attaching reports to an email

You can use the reporting attachment type in an email action to automatically generate a Kibana report and distribute it via email.

See Automating report generation.

Email action attributes

Email Address

An email address can contain two possible parts—​the address itself and an optional personal name as described in RFC 822. The address can be represented either as a string of the form user@host.domain or Personal Name <user@host.domain>. You can also specify an email address as an object that contains name and address fields.

Address List

A list of addresses can be specified as a an array: [ 'Personal Name <user1@host.domain>', 'user2@host.domain' ].

Configuring email accounts

Watcher can send email using any SMTP email service. Email messages can contain basic HTML tags. You can control which groups of tags are allowed by Configuring HTML Sanitization Options.

You configure the accounts Watcher can use to send email in the xpack.notification.email namespace in elasticsearch.yml. The password for the specified SMTP user is stored securely in the Elasticsearch keystore.

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.

Watcher provides three email profiles that control how MIME messages are structured: standard (default), gmail, and outlook. These profiles accommodate differences in how various email systems interpret the MIME standard. If you are using Gmail or Outlook, we recommend using the corresponding profile. Use the standard profile if you are using another email system.

For more information about configuring Watcher to work with different email systems, see:

• Sending email from Gmail
• Sending email from Outlook.com
• Sending email from Microsoft Exchange
• Sending email from Amazon SES (Simple Email Service)

If you configure multiple email accounts, you must either configure a default account or specify which account the email should be sent with in the email action.

xpack.notification.email:
  default_account: team1
  account:
    team1:
      ...
    team2:
      ...

Sending email from Gmail

Use the following email account settings to send email from the Gmail SMTP service:

xpack.notification.email.account:
    gmail_account:
        profile: gmail
        smtp:
            auth: true
            starttls.enable: true
            host: smtp.gmail.com
            port: 587
            user: <username>

To store the account SMTP password, use the keystore command (see secure settings)

bin/elasticsearch-keystore add xpack.notification.email.account.gmail_account.smtp.secure_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 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 Sign in using App Passwords for more information.

Sending email from Outlook.com

Use the following email account settings to send email action from the Outlook.com SMTP service:

xpack.notification.email.account:
    outlook_account:
        profile: outlook
        smtp:
            auth: true
            starttls.enable: true
            host: smtp-mail.outlook.com
            port: 587
            user: <email.address>

To store the account SMTP password, use the keystore command (see secure settings)

bin/elasticsearch-keystore add xpack.notification.email.account.outlook_account.smtp.secure_password

When sending emails, you have to provide a from address, either a default one in your account configuration or as part of the email action in the watch.

You need to use a unique App Password if two-step verification is enabled. See App passwords and two-step verification for more information.

Sending email from Amazon SES (Simple Email Service)

Use the following email account settings to send email from the Amazon Simple Email Service (SES) SMTP service:

xpack.notification.email.account:
    ses_account:
        email_defaults:
            from: <email address of service account> 
        smtp:
            auth: true
            starttls.enable: true
            starttls.required: true
            host: email-smtp.us-east-1.amazonaws.com 
            port: 587
            user: <username>

To store the account SMTP password, use the keystore command (see secure settings)

bin/elasticsearch-keystore add xpack.notification.email.account.ses_account.smtp.secure_password

You need to use your Amazon SES SMTP credentials to send email through Amazon SES. For more information, see Obtaining Your Amazon SES SMTP Credentials. You might also need to verify your email address or your whole domain at AWS.

Sending email from Microsoft Exchange

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

xpack.notification.email.account:
    exchange_account:
        profile: outlook
        email_defaults:
            from: <email address of service account> 
        smtp:
            auth: true
            starttls.enable: true
            host: <your exchange server>
            port: 587
            user: <email address of service account>

To store the account SMTP password, use the keystore command (see secure settings)

bin/elasticsearch-keystore add xpack.notification.email.account.exchange_account.smtp.secure_password

Configuring HTML sanitization options

The email action supports sending messages with an HTML body. However, for security reasons, Watcher sanitizes the HTML.

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

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

xpack.notification.email.html.sanitization:
    allow: _tables, _blocks
    disallow: h4, h5, h6

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

xpack.notification.email.html.sanitization.enabled: false