diff --git a/source/_integrations/smtp.markdown b/source/_integrations/smtp.markdown index e42633e8400..e9871ade9d0 100644 --- a/source/_integrations/smtp.markdown +++ b/source/_integrations/smtp.markdown @@ -12,17 +12,17 @@ ha_platforms: - notify --- -The `smtp` platform allows you to deliver notifications from Home Assistant to an e-mail recipient. +The SMTP platform allows you to deliver notifications from Home Assistant to an e-mail recipient. To enable notification by e-mail in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry notify: - - name: NOTIFIER_NAME + - name: "NOTIFIER_NAME" platform: smtp - sender: YOUR_SENDER - recipient: YOUR_RECIPIENT + sender: "YOUR_SENDER" + recipient: "YOUR_RECIPIENT" ``` {% configuration %} @@ -59,7 +59,7 @@ username: required: false type: string password: - description: Password for the SMTP server that belongs to the given username. If the password contains a colon it need to be wrapped in apostrophes. + description: Password for the SMTP server that belongs to the given username. Make sure to wrap it in double quotes; e.g., `"MY_PASSWORD"`. required: false type: string encryption: @@ -72,7 +72,7 @@ sender_name: required: false type: string debug: - description: Enables Debug, e.g., True or False. + description: Enables Debug, e.g., `true` or `false`. required: false type: boolean default: false @@ -83,19 +83,19 @@ A sample configuration entry for Google Mail. ```yaml # Example configuration.yaml entry notify: - - name: NOTIFIER_NAME + - name: "NOTIFIER_NAME" platform: smtp - server: smtp.gmail.com + server: "smtp.gmail.com" port: 587 timeout: 15 - sender: john@gmail.com + sender: "john@gmail.com" encryption: starttls - username: john@gmail.com - password: thePassword + username: "john@gmail.com" + password: "thePassword" recipient: - - james@gmail.com - - bob@gmail.com - sender_name: My Home Assistant + - "james@gmail.com" + - "bob@gmail.com" + sender_name: "My Home Assistant" ``` Keep in mind that Google has some extra layers of protection which need special attention (Hint: 'Less secure apps'). If you have 2-step verification enabled on your Google account, you'll need to use [an application-specific password](https://support.google.com/mail/answer/185833?hl=en). @@ -103,20 +103,20 @@ Keep in mind that Google has some extra layers of protection which need special To use the SMTP notification, refer to it in an automation or script like in this example: ```yaml - burglar: - alias: "Burglar Alarm" - sequence: - - service: shell_command.snapshot - - delay: - seconds: 1 - - service: notify.NOTIFIER_NAME - data: - title: "Intruder alert" - message: "Intruder alert at apartment!!" - data: - images: - - /home/pi/snapshot1.jpg - - /home/pi/snapshot2.jpg +burglar: + alias: "Burglar Alarm" + sequence: + - service: shell_command.snapshot + - delay: + seconds: 1 + - service: notify.NOTIFIER_NAME + data: + title: "Intruder alert" + message: "Intruder alert at apartment!!" + data: + images: + - /home/pi/snapshot1.jpg + - /home/pi/snapshot2.jpg ``` The optional `images` field adds in-line image attachments to the email. This sends a text/HTML multi-part message instead of the plain text default. @@ -124,74 +124,72 @@ The optional `images` field adds in-line image attachments to the email. This se The optional `html` field makes a custom text/HTML multi-part message, allowing total freedom for sending rich html emails. In them, if you need to attach images, you can pass both arguments (`html` and `images`), the attachments will be joined with the basename of the images, so they can be included in the html page with `src="cid:image_name.ext"`. ```yaml - burglar: - alias: "Burglar Alarm" - sequence: - - service: shell_command.snapshot - - delay: - seconds: 1 - - service: notify.NOTIFIER_NAME - data: - message: "Intruder alert at apartment!!" - data: - images: - - /home/pi/snapshot1.jpg - - /home/pi/snapshot2.jpg - html: > - - - - - - - Intruder alert - - - - - -
-
-

Intruder alert at apartment!!

-
-
-
-
-
- snapshot1 -
-
- snapshot2 -
+burglar: + alias: "Burglar Alarm" + sequence: + - service: shell_command.snapshot + - delay: + seconds: 1 + - service: notify.NOTIFIER_NAME + data: + message: "Intruder alert at apartment!!" + data: + images: + - /home/pi/snapshot1.jpg + - /home/pi/snapshot2.jpg + html: > + + + + + + + Intruder alert + + + + + +
+
+

Intruder alert at apartment!!

+
+
+
+
+
+ snapshot1 +
+
+ snapshot2
-
- - - - +
+
+ + + + ``` This platform is fragile and not able to catch all exceptions in a smart way because of the large number of possible configuration combinations. A combination that will work properly is port 587 and STARTTLS. It's recommended to enable STARTTLS, if possible. -Keep in mind that if the password contains a colon, it needs to be wrapped in apostrophes in the `configuration.yaml` file. - For Google Mail (smtp.gmail.com) an additional step in the setup process is needed. Google has some extra layers of protection which need special attention. By default, the usage by external applications, especially scripts, is limited. Visit the [Less secure apps](https://www.google.com/settings/security/lesssecureapps) page and enable it.