WARNING: Version 5.0 of the Elastic Stack has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Actions Webhook Action »

› › ›

Email Action

edit

Email Action

edit

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

edit

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>@<domainname>", 
      "subject" : "Watcher Notification", 
      "body" : "{{ctx.payload.hits.total}} error logs found" 
    }
  }
}

	The id of the action.
	The action type is set to `email`.
	One or more addresses to send the email to. Must be specified in the action definition or in the email account configuration.
	The subject of the email can contain static text and Mustache templates.
	The body of the email can contain static text and Mustache templates. Must be specified in the action definition or in the email account configuration.

Configuring Email Attachments

edit

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 or http. 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.

"actions" : {
  "email_admin" : {
    "email": {
      "to": "John Doe <john.doe@example.com>",
      "attachments" : {
        "my_report.pdf" : { 
          "http" : { 
            "content_type" : "application/pdf",
            "request" : {
              "url": "http://example.org/foo/my-report" 
            }
          }
        },
        "data.yml" : {
          "data" : {
            "format" : "yaml" 
          }
        }
      }
    }
  }
}

	The ID of the attachment, which is used as the file name in the email attachment.
	The type of the attachment and its specific configuration.
	The URL from which to retrieve the attachment.
	Data attachments default to JSON if you don’t specify the format.

Table 37. http attachment type attributes

Name	Description
`content_type`	Sets the content type for the email attachment. By default, the content type is extracted from the response sent by the HTTP service. You can explicitly specify the content type to ensure that the type is set correctly in the email in case the response does not specify the content type or it’s specified incorrectly. Optional.
`inline`	Configures as an attachment to sent with disposition `inline`. This allows the use of embedded images in HTML bodies, which are displayed in certain email clients. Optional. Defaults to `false`.
`request`	Contains the HTTP request attributes. At a minimum, you must specify the `url` attribute to configure the host and path to the service endpoint. See Webhook Action Attributes for the full list of HTTP request attributes. Required.

Table 38. data attachment type attributes

Name	Description
`format`	Attaches the watch data, equivalent to specifying `attach_data` in the watch configuration. Possible values are `json` or `yaml`. Defaults to `json` if not specified.

Attaching Reports to an Email

edit

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

For example, the following watch generates a report that contains the Error Monitoring dashboard and emails the report every hour:

PUT _xpack/watcher/watch/error_report
{
  "trigger" : {
    "schedule": {
      "interval": "1h"
    }
  },
  "actions" : {
  "email_admin" : { 
    "email": {
      "to": "'Recipient Name <recipient@example.com>'",
      "subject": "Error Monitoring Report",
      "attachments" : {
        "error_report.pdf" : {
          "http" : {
            "content_type" : "application/pdf",
            "request" : {
              "method": "POST", 
              "headers": {
                "kbn-xsrf": "reporting"
              },
              "read_timeout": "300s", 
              "url": "http://0.0.0.0:5601/api/reporting/generate/dashboard/Error-Monitoring?_g=(time:(from:now-1d%2Fd,mode:quick,to:now))&sync" 
            }
          }
        }
      }
    }
  }
 }
}

	You must configure at least one email account to enable Watcher to send email.
	Requests to the Reporting endpoints must use POST and include the `kbn-xsrf` header.
	Increase the `read_timeout` to give X-Pack reporting enough time to generate the report.
	This is an example Generation URL. You can copy and paste the URL for any report from the Kibana UI.

The interval between report requests must be longer than the time it takes to generate the reports—otherwise, the report queue can back up. To avoid this, increase the time between report requests.

By default, report generation times out if the report cannot be generated within 30 seconds. If you are generating reports that contain complex visualizations or your machine is slow or under constant heavy load, it might take longer than 30 seconds to generate a report. You can increase the timeout by setting xpack.reporting.queue.timeout in kibana.yml.

For more information, see Automating Report Generation.

Email Action Attributes

edit

Name	Required	Default	Description
`account`	no	the default account	The email account to use to send the email.
`from`	no	-	The email address from which the email will be sent. The `from` field can contain Mustache templates as long as it resolves to a valid email address.
`to`	yes	-	The email addresses of the `to` recipients. The `to` field can contain Mustache templates as long as it resolves to a valid email address.
`cc`	no	-	The email addresses of the `cc` recipients. The `cc` field can contain Mustache templates as long as it resolves to a valid email address.
`bcc`	no	-	The email addresses of the `bcc` recipients. The `bcc` field can contain Mustache templates as long as it resolves to a valid email address.
`reply_to`	no	-	The email addresses that will be set on the message’s `Reply-To` header. The `reply_to` field can contain Mustache templates as long as it resolves to a valid email address.
`subject`	no	-	The subject of the email. The subject can be static text or contain Mustache templates.
`body`	no	-	The body of the email. When this field holds a string, it will default to the text body of the email. Set as an object to specify either the text or the html body or both (using the fields below)
`body.text`	yes	-	The plain text body of the email. The body can be static text or contain Mustache templates. The email `body` must contain at least one `text` or `html` field.
`body.html`	yes	-	The html body of the email. The body can be static text or contain Mustache templates. This body will be sanitized to remove dangerous content such as scripts. This behavior can be disabled by setting `xpack.notification.email.html.sanitization.enabled: false` in `elasticsearch.yaml`. The email `body` must contain at least one `text` or `html` field.
`priority`	no	-	The priority of this email. Valid values are: `lowest`, `low`, `normal`, `high` and `highest`. The priority can contain a Mustache template as long as it resolves to one of the valid values.
`attachments`	no	-	Attaches the watch payload (`data` attachment) or a file retrieved from an HTTP service (`http` attachment) to the email. For more information, see Configuring Email Attachments.
`attach_data`	no	false	Indicates whether the watch execution data should be attached to the email. You can specify a Boolean value or an object. If `attach_data` is set to `true`, the data is attached as a YAML file. This attribute is deprecated, use the `attachments` attribute to add a `data` attachment to attach the watch payload.
`attach_data.format`	no	yaml	When `attach_data` is specified as an object, this field controls the format of the attached data. The supported formats are `json` and `yaml`. This attribute is deprecated, use the `attachments` attribute to add a `data` attachment to attach the watch payload.

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

edit

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.

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.

Currently, neither Watcher nor Shield provide a mechanism to encrypt settings in elasticsearch.yml. Because the email account credentials appear in plain text, you should limit access to elasticsearch.yml to the user that you use to run Elasticsearch.

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:

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

edit

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>
            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 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

edit

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: <username>
            password: <password>

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)

edit

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

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

smtp.host varies depending on the region

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

edit

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> 
            password: <password>

	Some organizations configure Exchange to validate that the `from` field is a valid local email account.
	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.

Configuring HTML Sanitization Options

edit

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

« Actions Webhook Action »