[[actions-email]]
==== Email Action

A watch <<actions, action>> that sends email notifications. To use the `email` action, you must configure at least one email account. For instructions, see <<email-services, Configuring Email Accounts>>.

See <<email-action-attributes>> for the supported attributes. Any attributes that are missing from the email action definition are looked up in the configuration of the account from which the email is being sent. The required attributes must either be set in the email action definition or the account's `email_defaults`.

[[configuring-email-actions]]
===== Configuring Email Actions

You configure email actions in a watch's `actions` array. Action-specific attributes are
specified using the `email` keyword.

The following snippet shows a basic email action definition:

[source,json]
--------------------------------------------------
"actions" : {
  "email_admin" : { <1>
    "transform" : { ... }, <2>
    "email": {
      "to": "'John Doe <john.doe@example.com>'", <3>
      "subject": "{{ctx.watch_id}} executed", <4>
      "body": "{{ctx.watch_id}} executed with {{ctx.payload.hits.total}} hits" <5>
    }
  }
}
--------------------------------------------------

<1> The id of the action.
<2> An optional <<transform, transform>> to transform the payload before processing the email.
<3> One or more addresses to send the email to. If not specified, the `to` address is read from the
    account's `email_defaults`.
<4> The subject of the email (static text or a Mustache <<templates, template>>).
<5> The body of the email (static text or a Mustache <<templates, template>>).


[[email-action-attributes]]
.Email Action Attributes
[options="header"]
|======
| Name                  |Required   | Default             | Description
| `account`             | no        | the default account | The <<email-account, account>> to use to send the email.
| `from`                | no        | -                   | The email <<email-address,address>> from which the email will be sent. The `from` field can contain Mustache <<templates, templates>> as long as it resolves to a valid email address.
| `to`                  | yes       | -                   | The email <<email-address,addresses>> of the `to` recipients. The `to` field can contain Mustache <<templates, templates>> as long as it resolves to a valid email address.
| `cc`                  | no        | -                   | The email <<email-address,addresses>> of the `cc` recipients. The `cc` field can contain Mustache <<templates, templates>> as long as it resolves to a valid email address.
| `bcc`                 | no        | -                   | The email <<email-address,addresses>> of the `bcc` recipients. The `bcc` field can contain Mustache <<templates, templates>> as long as it resolves to a valid email address.
| `reply_to`            | no        | -                   | The email <<email-address,addresses>> that will be set on the message's `Reply-To` header. The `reply_to` field can contain Mustache <<templates, 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, 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 bellow)
| `body.text`           | yes*      | -                   | The plain text body of the email. The body can be static text or contain Mustache <<templates, templates>>.
| `body.html`           | yes*      | -                   | The html body of the email. The body can be static text or contain Mustache <<templates, templates>>. This body will be sanitized to remove dangerous content such as scripts. This behavior can be disabled by setting `watcher.actions.email.sanitize_html: false` in elasticsearch.yaml.
| `priority`            | no        | -                   | The priority of this email. Valid values are: `lowest`, `low`, `normal`, `high` and `highest`. The priority can contain a Mustache <<templates, template>> as long as it resolves to one of the valid values.
| `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
called `data.yml`. If it's set to `false`, no data is attached. To control the format of the attached data, specify an object that contains a `format` field`.
| `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`. 
|======
* When setting the `body` object, at least one of its `text` or `html` fields must be defined.

[[email-address]]
Email Address::
    An email address can contain two possible parts--the address itself and an optional personal name as described in http://www.ietf.org/rfc/rfc822.txt[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]]
Address List::
    A list of addresses can either be specified as a comma-delimited string or as an array:
    + 
    `'Personal Name <user1@host.domain>, user2@host.domain'` or
    `[ 'Personal Name <user1@host.domain>', 'user2@host.domain' ]`

