jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-19 15:26:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add clarity to apostrophes meaning in SMTP docs (#17265)

Browse Source
This commit is contained in:
Franck Nijhof 2021-04-04 21:27:23 +02:00 committed by GitHub
parent 482422f675
commit f4f408b417
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 86 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
source/_integrations/smtp.markdown
View File

@ -12,17 +12,17 @@ ha_platforms:
- notify - 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: To enable notification by e-mail in your installation, add the following to your `configuration.yaml` file:
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
notify: notify:
- name: NOTIFIER_NAME - name: "NOTIFIER_NAME"
platform: smtp platform: smtp
sender: YOUR_SENDER sender: "YOUR_SENDER"
recipient: YOUR_RECIPIENT recipient: "YOUR_RECIPIENT"
``` ```
{% configuration %} {% configuration %}
@ -59,7 +59,7 @@ username:
required: false required: false
type: string type: string
password: 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 required: false
type: string type: string
encryption: encryption:
@ -72,7 +72,7 @@ sender_name:
required: false required: false
type: string type: string
debug: debug:
description: Enables Debug, e.g., True or False. description: Enables Debug, e.g., `true` or `false`.
required: false required: false
type: boolean type: boolean
default: false default: false
@ -83,19 +83,19 @@ A sample configuration entry for Google Mail.
```yaml ```yaml
# Example configuration.yaml entry # Example configuration.yaml entry
notify: notify:
- name: NOTIFIER_NAME - name: "NOTIFIER_NAME"
platform: smtp platform: smtp
server: smtp.gmail.com server: "smtp.gmail.com"
port: 587 port: 587
timeout: 15 timeout: 15
sender: john@gmail.com sender: "john@gmail.com"
encryption: starttls encryption: starttls
username: john@gmail.com username: "john@gmail.com"
password: thePassword password: "thePassword"
recipient: recipient:
- james@gmail.com - "james@gmail.com"
- bob@gmail.com - "bob@gmail.com"
sender_name: My Home Assistant 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). 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: To use the SMTP notification, refer to it in an automation or script like in this example:
```yaml ```yaml
burglar: burglar:
alias: "Burglar Alarm" alias: "Burglar Alarm"
sequence: sequence:
- service: shell_command.snapshot - service: shell_command.snapshot
- delay: - delay:
seconds: 1 seconds: 1
- service: notify.NOTIFIER_NAME - service: notify.NOTIFIER_NAME
data: data:
title: "Intruder alert" title: "Intruder alert"
message: "Intruder alert at apartment!!" message: "Intruder alert at apartment!!"
data: data:
images: images:
- /home/pi/snapshot1.jpg - /home/pi/snapshot1.jpg
- /home/pi/snapshot2.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. 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"`. 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 ```yaml
burglar: burglar:
alias: "Burglar Alarm" alias: "Burglar Alarm"
sequence: sequence:
- service: shell_command.snapshot - service: shell_command.snapshot
- delay: - delay:
seconds: 1 seconds: 1
- service: notify.NOTIFIER_NAME - service: notify.NOTIFIER_NAME
data: data:
message: "Intruder alert at apartment!!" message: "Intruder alert at apartment!!"
data: data:
images: images:
- /home/pi/snapshot1.jpg - /home/pi/snapshot1.jpg
- /home/pi/snapshot2.jpg - /home/pi/snapshot2.jpg
html: > html: >
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml"> <html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head> <head>
<meta charset="UTF-8"> <meta charset="UTF-8">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Intruder alert</title> <title>Intruder alert</title>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/css/bootstrap.min.css"> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/css/bootstrap.min.css">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css"> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css">
<style type="text/css"> <style type="text/css">
@font-face { @font-face {
font-family: 'Open Sans'; font-family: 'Open Sans';
font-style: normal; font-style: normal;
font-weight: 300; font-weight: 300;
src: local('Open Sans Light'), local('OpenSans-Light'), url(http://fonts.gstatic.com/s/opensans/v13/DXI1ORHCpsQm3Vp6mXoaTZS3E-kSBmtLoNJPDtbj2Pk.ttf) format('truetype'); src: local('Open Sans Light'), local('OpenSans-Light'), url(http://fonts.gstatic.com/s/opensans/v13/DXI1ORHCpsQm3Vp6mXoaTZS3E-kSBmtLoNJPDtbj2Pk.ttf) format('truetype');
} }
h1,h2,h3,h4,h5,h6 { h1,h2,h3,h4,h5,h6 {
font-family:'Open Sans',Arial,sans-serif; font-family:'Open Sans',Arial,sans-serif;
font-weight:400; font-weight:400;
margin:10px 0 margin:10px 0
} }
</style> </style>
</head> </head>
<body> <body>
<div class="jumbotron jumbotron-fluid" style="background-color: #f00a2d; color: white;"> <div class="jumbotron jumbotron-fluid" style="background-color: #f00a2d; color: white;">
<div class="container py-0"> <div class="container py-0">
<h1>Intruder alert at apartment!!</h1> <h1>Intruder alert at apartment!!</h1>
</div> </div>
</div> </div>
<div class="container-fluid"> <div class="container-fluid">
<div class="row"> <div class="row">
<div class="col-xs-12 col-md-6 px-0"> <div class="col-xs-12 col-md-6 px-0">
<img class="rounded" style="width: 100%;" <img class="rounded" style="width: 100%;"
alt="snapshot1" src="cid:snapshot1.jpg" /> alt="snapshot1" src="cid:snapshot1.jpg" />
</div> </div>
<div class="col-xs-12 col-md-6 px-0"> <div class="col-xs-12 col-md-6 px-0">
<img class="rounded" style="width: 100%;" <img class="rounded" style="width: 100%;"
alt="snapshot2" src="cid:snapshot2.jpg" /> alt="snapshot2" src="cid:snapshot2.jpg" />
</div>
</div> </div>
<br>
</div> </div>
</body> <br>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script> </div>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/js/bootstrap.min.js"></script> </body>
</html> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-alpha.5/js/bootstrap.min.js"></script>
</html>
``` ```
This platform is fragile and not able to catch all exceptions in a smart way because of the large number of possible configuration combinations. 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. 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 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. 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.