kibana/docs/user/alerting/action-types/email.asciidoc

[role="xpack"]
[[email-action-type]]
=== Email connector and action
++++
<titleabbrev>Email</titleabbrev>
++++

The email connector uses the SMTP protocol to send mail messages, using an integration of https://nodemailer.com/[Nodemailer]. Email message text is sent as both plain text and html text.

NOTE: For emails to have a footer with a link back to {kib}, set the <<server-publicBaseUrl, `server.publicBaseUrl`>> configuration setting.

[float]
[[email-connector-configuration]]
==== Connector configuration

Email connectors have the following configuration properties.

Name::      The name of the connector. The name is used to identify a  connector in the management UI connector listing, or in the connector list when configuring an action.
Sender::    The from address for all emails sent with this connector. This can be specified in `user@host-name` format or as `"human name <user@host-name>"` format. See the https://nodemailer.com/message/addresses/[Nodemailer address documentation] for more information.
Host::      Host name of the service provider. If you are using the <<action-settings, `xpack.actions.allowedHosts`>> setting, make sure this hostname is added to the allowed hosts.
Port::      The port to connect to on the service provider.
Secure::    If true, the connection will use TLS when connecting to the service provider. Refer to the https://nodemailer.com/smtp/#tls-options[Nodemailer TLS documentation] for more information.  If not true, the connection will initially connect over TCP, then attempt to switch to TLS via the SMTP STARTTLS command.
Require authentication:: If true, a username and password for login type authentication must be provided.
Username::  Username for login type authentication.
Password::  Password for login type authentication.

[float]
[[Preconfigured-email-configuration]]
==== Preconfigured connector type

[source,text]
--
 my-email:
   name: preconfigured-email-connector-type
   actionTypeId: .email
   config:
     from: testsender@test.com
     host: validhostname
     port: 8080
     secure: false
   secrets:
     user: testuser
     password: passwordkeystorevalue
--

Config defines information for the connector type.

`service`:: The name of a https://nodemailer.com/smtp/well-known/[well-known email service provider]. If `service` is provided, `host`, `port`, and `secure` properties are ignored. For more information on the `gmail` service value, see the https://nodemailer.com/usage/using-gmail/[Nodemailer Gmail documentation].
`from`:: An email address that corresponds to *Sender*.
`host`:: A string that corresponds to *Host*.
`port`:: A number that corresponds to *Port*.
`secure`:: A boolean that corresponds to *Secure*.
`hasAuth`:: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.

Secrets defines sensitive information for the connector type.

`user`:: A string that corresponds to *Username*. Required if `hasAuth` is set to `true`.
`password`:: A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>. Required if `hasAuth` is set to `true`.


[float]
[[email-action-configuration]]
==== Action configuration

Email actions have the following configuration properties.

To, CC, BCC::    Each item is a list of addresses. Addresses can be specified in `user@host-name` format, or in `name <user@host-name>` format. One of To, CC, or BCC must contain an entry.
Subject::       The subject line of the email.
Message::       The message text of the email. Markdown format is supported.

[[configuring-email]]
==== Configuring email accounts for well-known services

The email connector can send email using many popular SMTP email services.

For more information about configuring the email connector to work with different email systems, refer to:

* <<gmail>>
* <<outlook>>
* <<exchange>>
* <<amazon-ses>>

For other email servers, you can check the list of well-known services that Nodemailer supports in the JSON file https://github.com/nodemailer/nodemailer/blob/master/lib/well-known/services.json[well-known/services.json].  The properties of the objects in those files &mdash; `host`, `port`, and `secure` &mdash; correspond to the same email connector configuration properties.  A missing `secure` property in the "well-known/services.json" file is considered `false`.  Typically, `port: 465` uses `secure: true`, and `port: 25` and `port: 587` use `secure: false`.

[float]
[[gmail]]
===== Sending email from Gmail

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

[source,text]
--------------------------------------------------
  config:
    host: smtp.gmail.com
    port: 465
    secure: true
  secrets:
    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 the action 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 {kib}. See
https://support.google.com/accounts/answer/185833?hl=en[Sign in using App Passwords]
for more information.

[float]
[[outlook]]
===== Sending email from Outlook.com

Use the following email connector configuration to send email from the
https://www.outlook.com/[Outlook.com] SMTP service:

[source,text]
--------------------------------------------------
config:
    host: smtp.office365.com
    port: 587
    secure: false
secrets:
    user: <email.address>
    password: <password>
--------------------------------------------------

When sending emails, you must provide a `from` address, either as the default 
in your connector configuration or as part of the email action in the rule.

NOTE:   You must 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.

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

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

[source,text]
--------------------------------------------------
config:
    host: email-smtp.us-east-1.amazonaws.com <1>
    port: 465
    secure: true
secrets:
    user: <username>
    password: <password>
--------------------------------------------------
<1> `config.host` varies depending on the region

NOTE:   You must 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]. You might also need to verify
        https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses.html[your email address]
        or https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-domains.html[your whole domain]
        at AWS.

[float]
[[exchange]]
===== Sending email from Microsoft Exchange

Use the following email connector configuration to send email from Microsoft
Exchange:

[source,text]
--------------------------------------------------
config:
    host: <your exchange server>
    port: 465
    secure: true
    from: <email address of service account> <1>
secrets:
    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.
    Check with your system administrator if you receive
    authentication-related failures.