[actions] improve email action doc #90020

pmuellr · 2021-02-02T15:21:01Z

resolves #88333

Fixed:

add note that secure: false will use TLS, but after an initial connection
with TCP; we have been getting questions from customers who believed that
secure: false implied TLS was not used at all.
added a link to the nodemailer "well-known services" module, to allow
customers to see examples of other email service configurations
updated the Outlook config example to use the current nodemailer values
couple of other small tweaks

resolves elastic#88333 Fixed: - add note that `secure: false` will use TLS, but after an initial connection with TCP; we have been getting questions from customers who believed that `secure: false` implied TLS was not used at all. - added a link to the nodemailer "well-known services" module, to allow customers to see examples of other email service configurations - updated the Outlook config example to use the current nodemailer values - couple of other small tweaks

pmuellr · 2021-02-02T16:20:59Z

doc preview: https://kibana_90020.docs-preview.app.elstc.co/guide/en/kibana/master/email-action-type.html

elasticmachine · 2021-02-02T18:01:45Z

Pinging @elastic/kibana-alerting-services (Team:Alerting Services)

pmuellr · 2021-02-02T18:02:18Z

could you wordsmith the changes, @gchaps ?

gchaps · 2021-02-02T22:00:48Z

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

@@ -14,7 +14,7 @@ Name::      The name of the connector. The name is used to identify a  connector
 Sender::    The from address for all emails sent with this connector, specified in `user@host-name` format.
 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. See https://nodemailer.com/smtp/#tls-options[nodemailer TLS documentation] for more information.
+Secure::    If true the connection will use TLS when connecting to the service provider. See 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.


Suggested change

Secure:: If true the connection will use TLS when connecting to the service provider. See 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.

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.

gchaps · 2021-02-02T22:05:20Z

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

@@ -92,6 +92,8 @@ systems, refer to:
 * <<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 action configuration properties.  A missing `secure` property in the "well-known/services.json" file is considered `false`.  Generally, `port: 465` uses `secure: true`, and `port: 25` and `port: 587` use `secure: false`.


Suggested change

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 action configuration properties. A missing `secure` property in the "well-known/services.json" file is considered `false`. Generally, `port: 465` uses `secure: true`, and `port: 25` and `port: 587` use `secure: false`.

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 action 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`.

elasticmachine · 2021-02-03T21:43:37Z

Pinging @elastic/kibana-docs (Team:Docs)

YulNaumenko

LGTM

pmuellr · 2021-02-05T19:30:20Z

@elasticmachine merge upstream

gchaps

One minor comment:

add a comma after "If true"

If true, the connection will use TLS...

resolves elastic#88333 Fixed: - add note that `secure: false` will use TLS, but after an initial connection with TCP; we have been getting questions from customers who believed that `secure: false` implied TLS was not used at all. - added a link to the nodemailer "well-known services" module, to allow customers to see examples of other email service configurations - updated the Outlook config example to use the current nodemailer values - couple of other small tweaks

resolves #88333 Fixed: - add note that `secure: false` will use TLS, but after an initial connection with TCP; we have been getting questions from customers who believed that `secure: false` implied TLS was not used at all. - added a link to the nodemailer "well-known services" module, to allow customers to see examples of other email service configurations - updated the Outlook config example to use the current nodemailer values - couple of other small tweaks

* master: (55 commits) [APM-UI][E2E] use githubNotify step (elastic#90514) [APM] Export ProcessorEvent type (elastic#90540) [Lens] Retain column config (elastic#90048) [Data Table] Add unit tests (elastic#90173) Migrate most plugins to synchronous lifecycle (elastic#89562) skip flaky suite (elastic#90555) skip flaky suite (elastic#64473) [actions] improve email action doc (elastic#90020) [Fleet] Support Fleet server system indices (elastic#89372) skip flaky suite (elastic#90552) Bump immer dependencies (elastic#90267) Unrevert "Migrations v2: don't auto-create indices + FTR/esArchiver support (elastic#85778)" (elastic#89992) [Search Sessions] Use sync config (elastic#90138) chore(NA): add safe guard to remove bazelisk from yarn global at bootstrap (elastic#90538) [test] Await retry.waitFor (elastic#90456) chore(NA): integrate build buddy with our bazel setup and remote cache for ci (elastic#90116) Skip failing suite (elastic#90526) [Fleet] Fix incorrect conversion of string to numeric values in agent YAML (elastic#90371) [Docs] Update reporting troubleshooting for arm rhel/centos (elastic#90385) chore(NA): build bazel projects all at once in the distributable build process (elastic#90328) ...

pmuellr added 2 commits February 2, 2021 10:19

add a bit more on the smtp port / secure combinations

523ad9c

pmuellr added Feature:Alerting Team:ResponseOps Label for the ResponseOps team (formerly the Cases and Alerting teams) v7.12.0 v8.0.0 release_note:skip Skip the PR/issue when compiling release notes labels Feb 2, 2021

pmuellr marked this pull request as ready for review February 2, 2021 18:01

pmuellr requested a review from a team as a code owner February 2, 2021 18:01

gchaps reviewed Feb 2, 2021

View reviewed changes

gchaps added the Team:Docs label Feb 3, 2021

YulNaumenko approved these changes Feb 4, 2021

View reviewed changes

fixes from PR review

6dcff08

Merge branch 'master' into actions/improve-email-doc

97ecf6c

gchaps approved these changes Feb 5, 2021

View reviewed changes

more fixes from PR review

932be43

pmuellr merged commit e221992 into elastic:master Feb 8, 2021

pmuellr mentioned this pull request Feb 8, 2021

[7.x] [actions] improve email action doc (#90020) #90562

Merged

pmuellr added the backported label Feb 8, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[actions] improve email action doc #90020

[actions] improve email action doc #90020

pmuellr commented Feb 2, 2021

pmuellr commented Feb 2, 2021

elasticmachine commented Feb 2, 2021

pmuellr commented Feb 2, 2021

gchaps Feb 2, 2021

gchaps Feb 2, 2021

elasticmachine commented Feb 3, 2021

YulNaumenko left a comment

pmuellr commented Feb 5, 2021

gchaps left a comment

	Secure:: If true the connection will use TLS when connecting to the service provider. See 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.
	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.

[actions] improve email action doc #90020

[actions] improve email action doc #90020

Conversation

pmuellr commented Feb 2, 2021

pmuellr commented Feb 2, 2021

elasticmachine commented Feb 2, 2021

pmuellr commented Feb 2, 2021

gchaps Feb 2, 2021

Choose a reason for hiding this comment

gchaps Feb 2, 2021

Choose a reason for hiding this comment

elasticmachine commented Feb 3, 2021

YulNaumenko left a comment

Choose a reason for hiding this comment

pmuellr commented Feb 5, 2021

gchaps left a comment

Choose a reason for hiding this comment