* Renaming alerts to rules * Updating formatted messages * Updating i18n labels * Completed renaming in UI * Updating client routes including redirect * wip docs update * Reverting title changes for now * Fixing types check * Fixing unit tests * Fixing functional test * Fixing functional test * docs wip * wip docs update * Finished first run through docs * docs docs docs * Fixing bad merge * Fixing functional test * Docs cleanup * Cleaning up i18n labels * Fixing functional test * Updating screenshots * Updating screenshots * Updating screenshots * Updating terminology in alerting examples * Updating terminology in alerting examples Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
188 lines
7.9 KiB
Plaintext
188 lines
7.9 KiB
Plaintext
[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 — `host`, `port`, and `secure` — 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.
|