diff --git a/Notify_email.md b/Notify_email.md new file mode 100644 index 0000000..a6189b3 --- /dev/null +++ b/Notify_email.md @@ -0,0 +1,66 @@ +## E-Mail Notifications +* **Source**: n/a +* **Icon Support**: no +* **Message Format**: Text +* **Message Limit**: 32768 Characters per message + +## Using Built-In Email Services +If you are using one of the following Buil-In E-Mail services, then setting up this notification service has never been easier. If your provider isn't on the list and you'd like to request it, just [open up a ticket](https://github.com/caronc/nzb-notify/issues) and request it. However, if your provider isn't on the list you're not out of luck. Custom email servers are a little bit more complicated, but still work. See the section under this entitled *Customer Servers*). + +The following syntaxes work right out of the box: +* mailto://{userid}:{password}@**yahoo.com** +* mailto://{userid}:{password}@**hotmail.com** +* mailto://{userid}:{password}@**live.com** +* mailto://{userid}:{password}@**prontomail.com** +* mailto://{userid}:{password}@**gmail.com** + +Secure connections are always implied whether you choose to use **mailto://** or **mailtos://** + +**Note** Google Users using the 2 Step Verification Process will be required to generate an **apppassword** from [here](https://security.google.com/settings/security/apppasswords) that you can use in the {password} field. + +## Using Custom Servers Syntax +If you're using your own SMTP Server or one that simply isn't in the *Built-In* list defined in the previous section then things get a wee-bit more complicated. + +First off, secure vs insecure emails are defined by **mailto://** (port 25) and **mailtos://** (port 587) where **mailtos://** will enable TLS prior to sending the user and password. + +If your SMTP server is identified by a different hostname than what is identified by the suffix of your email, then you'll need to specify it as an argument; for example: +* mailtos://userid:password@server.com?smtp=smtp.server.com + +If you want to adjust the email's *ReplyTo* address, then you can do the following: +* mailtos://userid:password@server.com?smtp=smtp.server.com&from=noreply@server.com + +You can also adjust the ReplyTo's Name too: +* mailtos://userid:password@server.com?smtp=smtp.server.com&from=noreply@server.com&name=Optional%20Name +Since URL's can't have spaces in them, you'll need to use '**%20**' as a place-holder for one (if needed). In the example above, the email would actually be received as *Optional Name*. + +Here are some example syntaxes you can use when doing the custom approach: +* **mailto**:://**{userid}**:**{password}**@**{domain}** +* **mailto**:://**{userid}**:**{password}**@**{domain}**:{port}?smtp=**{smtp_server}** +* **mailto**:://**{userid}**:**{password}**@**{domain}**:{port}?from=**{from_email}**&name=**{from_name}** + +Some mail servers will require your {userid} to be your full email address. In these cases, you'll need to specify your username in the url as an attribute like so: +* **mailto**:://**{password}**@**{domain}**:{port}?user=**{userid}** + +### Parameter Breakdown +| Variable | Required | Description +| ----------- | -------- | ----------- +| userid | Yes | The account login to your SMTP server; if this is an email you must specify this near the end of the URL as an argument. +| password | Yes | The password required to send an email via your SMTP Server. +| domain | Yes | If your email address was **test@example.com** then *example.com* is your domain. You must provide this as part of the URL string! +| port | No | The port your SMTP server is listening on. By default the port is **25** for **mailto://** and **587** for all **mailtos://** references. +| smtp_server | No | If the SMTP server differs from your specified domain, then you'll want to specify it as an argument in your URL. +| from_email | No | If you want the email address *ReplyTo* address to be something other then your own email address, then you can specify it here. +| from_name | No | With respect to {from_email}, this allows you to provide a name with your *ReplyTo* address. +| timeout | No | How long to wait for your SMTP server in seconds before giving up. The default is 30 seconds. If you want to adjust the timeout, simply specify it as an argument on your URL. + +To eliminate any confusion, any url parameter (key=value) specified will over-ride what was detected in the url; hence: +* mailto://usera:pass123@domain.com?user=foobar@domain.com: the userid of _foobar_ would over-ride the userid _usera_ specified. However since the password was not over-ridden, the password of _pass123_ would be used still. + +#### Example +Send a email notification to our hotmail account: +```bash +# It's really easy if you're using a built in provider +# Built-In providers look after handling the little details such as +# the SMTP server, port, enforcing a secure connection, etc +notify mailto:///example:mypassword@hotmail.com +```