node-red-nodes/social/email/README.md

87 lines
3.8 KiB
Markdown
Raw Normal View History

node-red-node-email
===================
<a href="http://nodered.org" target="info">Node-RED</a> nodes to send and receive simple emails.
Pre-requisite
-------------
You will need valid email credentials for your email server. For GMail this may mean
getting an application password if you have two-factor authentication enabled.
XOAuth2 for Email-In node (#975) * Update PULL_REQUEST_TEMPLATE.md * Add new UI elements to Email In node Locale for en-US Added Auth type and Token field to Email IN Dynamically appear based on selection * XOAUTH2 IMAP Minor UI changes. Exposing only XOAuth2. Picks up raw access token from input message specified. Only works for IMAP Token formatted by node for Exchange and GMail, won't work on other providers. Only works on trigger, not timer TODO: Add POP XOAUTH2 capability Add SMTP XOAUTH2 capability Add option to pass SASL XAOUTH2 token rather than raw OAUTH2 token * SASL Format Added checkbox to turn off SASL formatting if the user wants to do this themselves * XOAuth2 forces input Using XOauth2 forces triggered node, and automatic trigger sets auth to basic; XOAuth2 needs token from flow * Error reporting Password missing error only occurs if set to basic authentication. Token missing only occurs if set to XOAuth2. * Unit tests Make sure basic authentication is selected by default, and that an additional input is created and timed triggers are turned off for XOauth2 * Cleanup and README Remove old code, update readme * XOauth2 IMAP Release Prevent XOAuth2 being used for POP. Update PR Template. Updated help file. Bumped version to 1.19-beta * Update POP3 dependency Removed dependency to poplib.js, moved to node-pop3. Re-wrote checkPOP3 function asynchronously using the new library. Added some node.status changes to mimic IMAP behaviour. * XOAUTH2 POP3 Added checking for authentication type to allow XOauth2 tokens to be sent to POP server. Turned off UI restrictions for this functionality. * XOAUTH2 POP3 Release Updated help docs and version to reflect changes. * Add new UI elements to Email Out node Add option for XAouth2 for SMTP node * XOAUTH2 SMTP Exposing functionality for OAuth2 through Nodemailer. Added some error reporting if credentials are missing to match the Email-In node. * XOAUTH2 SMTP Release Updated help file to reflect changes. * Unit Tests for Email Out Modified tests to allow these unit tests to pass, but does not address the fault caused by the Node Test Helper - credentials only loaded after the flow has been loaded. --------- Co-authored-by: Dave Conway-Jones <dceejay@users.noreply.github.com>
2023-03-27 21:27:47 +02:00
For Exchange and Outlook 365 you must use OAuth2.0.
**Notes **:
Version 2.x of this node required **Node.js v12** or newer.
Version 1.x of this node requires **Node.js v8** or newer.
2018-05-01 23:06:54 +02:00
Install
-------
You can install by using the `Menu - Manage Palette` option, or running the following command in your
Node-RED user directory - typically `~/.node-red`
cd ~/.node-red
npm i node-red-node-email
GMail users
-----------
If you are accessing GMail you may need to either enable <a target="_new" href="https://support.google.com/mail/answer/185833?hl=en">an application password</a>,
or enable <a target="_new" href="https://support.google.com/accounts/answer/6010255?hl=en">less secure access</a> via your Google account settings.</p>
2018-05-01 23:06:54 +02:00
XOAuth2 for Email-In node (#975) * Update PULL_REQUEST_TEMPLATE.md * Add new UI elements to Email In node Locale for en-US Added Auth type and Token field to Email IN Dynamically appear based on selection * XOAUTH2 IMAP Minor UI changes. Exposing only XOAuth2. Picks up raw access token from input message specified. Only works for IMAP Token formatted by node for Exchange and GMail, won't work on other providers. Only works on trigger, not timer TODO: Add POP XOAUTH2 capability Add SMTP XOAUTH2 capability Add option to pass SASL XAOUTH2 token rather than raw OAUTH2 token * SASL Format Added checkbox to turn off SASL formatting if the user wants to do this themselves * XOAuth2 forces input Using XOauth2 forces triggered node, and automatic trigger sets auth to basic; XOAuth2 needs token from flow * Error reporting Password missing error only occurs if set to basic authentication. Token missing only occurs if set to XOAuth2. * Unit tests Make sure basic authentication is selected by default, and that an additional input is created and timed triggers are turned off for XOauth2 * Cleanup and README Remove old code, update readme * XOauth2 IMAP Release Prevent XOAuth2 being used for POP. Update PR Template. Updated help file. Bumped version to 1.19-beta * Update POP3 dependency Removed dependency to poplib.js, moved to node-pop3. Re-wrote checkPOP3 function asynchronously using the new library. Added some node.status changes to mimic IMAP behaviour. * XOAUTH2 POP3 Added checking for authentication type to allow XOauth2 tokens to be sent to POP server. Turned off UI restrictions for this functionality. * XOAUTH2 POP3 Release Updated help docs and version to reflect changes. * Add new UI elements to Email Out node Add option for XAouth2 for SMTP node * XOAUTH2 SMTP Exposing functionality for OAuth2 through Nodemailer. Added some error reporting if credentials are missing to match the Email-In node. * XOAUTH2 SMTP Release Updated help file to reflect changes. * Unit Tests for Email Out Modified tests to allow these unit tests to pass, but does not address the fault caused by the Node Test Helper - credentials only loaded after the flow has been loaded. --------- Co-authored-by: Dave Conway-Jones <dceejay@users.noreply.github.com>
2023-03-27 21:27:47 +02:00
Office 365 users
----------------
XOAuth2 for Email-In node (#975) * Update PULL_REQUEST_TEMPLATE.md * Add new UI elements to Email In node Locale for en-US Added Auth type and Token field to Email IN Dynamically appear based on selection * XOAUTH2 IMAP Minor UI changes. Exposing only XOAuth2. Picks up raw access token from input message specified. Only works for IMAP Token formatted by node for Exchange and GMail, won't work on other providers. Only works on trigger, not timer TODO: Add POP XOAUTH2 capability Add SMTP XOAUTH2 capability Add option to pass SASL XAOUTH2 token rather than raw OAUTH2 token * SASL Format Added checkbox to turn off SASL formatting if the user wants to do this themselves * XOAuth2 forces input Using XOauth2 forces triggered node, and automatic trigger sets auth to basic; XOAuth2 needs token from flow * Error reporting Password missing error only occurs if set to basic authentication. Token missing only occurs if set to XOAuth2. * Unit tests Make sure basic authentication is selected by default, and that an additional input is created and timed triggers are turned off for XOauth2 * Cleanup and README Remove old code, update readme * XOauth2 IMAP Release Prevent XOAuth2 being used for POP. Update PR Template. Updated help file. Bumped version to 1.19-beta * Update POP3 dependency Removed dependency to poplib.js, moved to node-pop3. Re-wrote checkPOP3 function asynchronously using the new library. Added some node.status changes to mimic IMAP behaviour. * XOAUTH2 POP3 Added checking for authentication type to allow XOauth2 tokens to be sent to POP server. Turned off UI restrictions for this functionality. * XOAUTH2 POP3 Release Updated help docs and version to reflect changes. * Add new UI elements to Email Out node Add option for XAouth2 for SMTP node * XOAUTH2 SMTP Exposing functionality for OAuth2 through Nodemailer. Added some error reporting if credentials are missing to match the Email-In node. * XOAUTH2 SMTP Release Updated help file to reflect changes. * Unit Tests for Email Out Modified tests to allow these unit tests to pass, but does not address the fault caused by the Node Test Helper - credentials only loaded after the flow has been loaded. --------- Co-authored-by: Dave Conway-Jones <dceejay@users.noreply.github.com>
2023-03-27 21:27:47 +02:00
If you are accessing Exchnage you will need to register an application through their platform and use OAuth2.0.
<a target="_new" href="https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#get-an-access-token">Details on how to do this can be found here.</a>
Usage
-----
Nodes to send and receive simple emails.
### Input node
Fetches emails from an IMAP or POP3 server and forwards them onwards as messages if not already seen.
The subject is loaded into `msg.topic` and `msg.payload` is the plain text body.
If there is text/html then that is returned in `msg.html`. `msg.from` and
`msg.date` are also set if you need them.
Additionally `msg.header` contains the complete header object including
**to**, **cc** and other potentially useful properties.
XOAuth2 for Email-In node (#975) * Update PULL_REQUEST_TEMPLATE.md * Add new UI elements to Email In node Locale for en-US Added Auth type and Token field to Email IN Dynamically appear based on selection * XOAUTH2 IMAP Minor UI changes. Exposing only XOAuth2. Picks up raw access token from input message specified. Only works for IMAP Token formatted by node for Exchange and GMail, won't work on other providers. Only works on trigger, not timer TODO: Add POP XOAUTH2 capability Add SMTP XOAUTH2 capability Add option to pass SASL XAOUTH2 token rather than raw OAUTH2 token * SASL Format Added checkbox to turn off SASL formatting if the user wants to do this themselves * XOAuth2 forces input Using XOauth2 forces triggered node, and automatic trigger sets auth to basic; XOAuth2 needs token from flow * Error reporting Password missing error only occurs if set to basic authentication. Token missing only occurs if set to XOAuth2. * Unit tests Make sure basic authentication is selected by default, and that an additional input is created and timed triggers are turned off for XOauth2 * Cleanup and README Remove old code, update readme * XOauth2 IMAP Release Prevent XOAuth2 being used for POP. Update PR Template. Updated help file. Bumped version to 1.19-beta * Update POP3 dependency Removed dependency to poplib.js, moved to node-pop3. Re-wrote checkPOP3 function asynchronously using the new library. Added some node.status changes to mimic IMAP behaviour. * XOAUTH2 POP3 Added checking for authentication type to allow XOauth2 tokens to be sent to POP server. Turned off UI restrictions for this functionality. * XOAUTH2 POP3 Release Updated help docs and version to reflect changes. * Add new UI elements to Email Out node Add option for XAouth2 for SMTP node * XOAUTH2 SMTP Exposing functionality for OAuth2 through Nodemailer. Added some error reporting if credentials are missing to match the Email-In node. * XOAUTH2 SMTP Release Updated help file to reflect changes. * Unit Tests for Email Out Modified tests to allow these unit tests to pass, but does not address the fault caused by the Node Test Helper - credentials only loaded after the flow has been loaded. --------- Co-authored-by: Dave Conway-Jones <dceejay@users.noreply.github.com>
2023-03-27 21:27:47 +02:00
Modern authentication through OAuth2.0 is supported, but must be triggered by an incoming access token and
can only be automatically triggered upstream.
### Output node
2016-08-03 10:01:28 +02:00
Sends the `msg.payload` as an email, with a subject of `msg.topic`.
The default message recipient can be configured in the node, if it is left blank it should be set using the `msg.to` property of the incoming message. You can also specify any or all of: `msg.cc`, `msg.bcc`, `msg.replyTo`, `msg.inReplyTo`, `msg.references`, `msg.headers`, or `msg.priority` properties.
The email *from* can be set using `msg.from` but not all mail services allow
this unless `msg.from` is also a valid userid or email address associated with
the password. Note: if `userid` or msg.from does not contain a valid email
address (userxx@some_domain.com), you may see *(No Sender)* in the email.
2016-08-03 10:01:28 +02:00
The payload can be html format. You can also specify `msg.plaintext` if the main payload is html.
If the payload is a binary buffer then it will be converted to an attachment.
The filename should be set using `msg.filename`. Optionally
`msg.description` can be added for the body text.
Alternatively you may provide `msg.attachments` which should contain an array of one or
more attachments in <a href="https://nodemailer.com/message/attachments/" target="_new">nodemailer</a> format.
If required by your recipient you may also pass in a `msg.envelope` object, typically containing extra from and to properties.
If you have own signed certificates, Nodemailer can complain about that and refuse sending the message. In this case you can try switching off TLS.
Use secure connection - If enabled the connection will use TLS when connecting to server. If disabled then TLS is used if server supports the STARTTLS extension. In most cases set this to enabled if you are connecting to port 465. For port 587 or 25 keep it disabled.
This node uses the *nodemailer* npm module.