@warren-bank/email-relay NPM

email-relay

SMTP proxy server with middleware capability.

Installation:

npm install --global @warren-bank/email-relay

Usage:

email-relay <options>

options:
========
"-H"
"--help"
    Print a help message describing all command-line options.

"-V"
"--version"
    Display the version.

"-D"
"--debug"
    Boolean flag to enable printing of debug logs
    for all messages received by the local SMTP server,
    and to disable their forwarding to the remote SMTP server.

"-lp" <number>
"--local-port" <number>
    Specify the port number that the local SMTP server listens on.
    [Default: 25]

"-h" <hostname>
"--remote-host" <hostname>
    Specify the hostname of the remote SMTP server.
    [Required]

"-rp" <number>
"--remote-port" <number>
    Specify the port number of the remote SMTP server.
    [Default: 25]

"-s"
"--remote-secure"
    Boolean flag to indicate that the remote SMTP server uses a secure (TLS or SSL) connection.
    [Default: false]

"-u" <username>
"--remote-username" <username>
    Specify the username for account authentication on the remote SMTP server.
    [Optional]

"-p" <password>
"--remote-password" <password>
    Specify the password for account authentication on the remote SMTP server.
    [Optional]

"-f" <email-address>
"--send-email-from" <email-address>
    Specify an email address to override the "from" sender
    for all messages received by the local SMTP server,
    before they are forwarded to the remote SMTP server.
    [Optional]

"-m" </path/to/file.js>
"--middleware" </path/to/file.js>
    Specifies the absolute filepath to a CommonJS module that exports a single function.
    This function can be used to conditionally modify any attribute
    of all messages received by the local SMTP server,
    before they are forwarded to the remote SMTP server.
    [Optional. Can be used more than once.]

"-LTT1"
"--legacy-tls-tweak-01"
    Boolean flag to enable the addition of a configuration tweak
    that may be required to support a secure connection to the remote SMTP server
    when either the local client (version of Node) or remote server only supports legacy protocols.
    This configuration tweak is:
      options.tls.ciphers = 'SSLv3'

"-LTT2"
"--legacy-tls-tweak-02"
    Boolean flag to enable the addition of a configuration tweak
    that may be required to support a secure connection to the remote SMTP server
    when either the local client (version of Node) or remote server only supports legacy protocols.
    This configuration tweak is:
      options.tls.minVersion = 'TLSv1'

"-LTT3"
"--legacy-tls-tweak-03"
    Boolean flag to enable the addition of a configuration tweak
    that may be required to support a secure connection to the remote SMTP server
    when either the local client (version of Node) or remote server only supports legacy protocols.
    This configuration tweak is:
      options.tls.rejectUnauthorized = false

Middleware:

each middleware function is synchronously processed in the order given on the command-line
the same message configuration object is passed as an input parameter to each middleware function
this object is passed by reference, and its attributes can be directly modified

Running Locally for Testing:

download and unzip into any local directory
open terminal and change directory to where the repo snapshot was unzipped:
```
  cd /path/to/node-email-relay-master
```
install dependencies:
```
  npm install
```
start server in debug mode and pipe output to a log file:
```
  npm start -- -D >debug.log 2>&1
```
test server by sending a message to it:
```
  npm run "tests:01"
```
inspect the debug log:
```
  cat debug.log
```

Troubleshooting:

a secure (TLS or SSL) connection to the remote SMTP server
- nodemailer documentation says that:
  - the --remote-secure option should only be used with --remote-port 465. for all other port numbers, the connection will upgrade to use TLS if the remote server supports it.
  - the -LTT3 option is applicable when using an older version of Node, that does not fully support the certificate chain of the newest Let's Encrypt certificates.
  - the -LTT2 option is applicable when connecting to a remote SMTP server that only supports TLS v1.1 or lower. relevant Node documentation:
    - minVersion tls option
    - tls.DEFAULT_MIN_VERSION in recent versions of Node is TLSv1.2
- nodemailer issue 165 says that:
  - the -LTT1 option is applicable when connecting to a remote SMTP server that only supports SSL v3. relevant Node documentation:
    - ciphers tls option

Real-World Example for Yahoo Mail:

documentation for connecting to remote SMTP server: | | | |----------|---------------------------| | hostname | smtp.mail.yahoo.com | | port | 465 (SSL) or 587 (SSL) | | secure | true | | username | me@yahoo.com | | password | my-generated-app-password |
account page to generate a Yahoo Mail app password:
- Account Security > Generate app password

<options>:

  my_email='me@yahoo.com'
  my_password='0123456789abcdef'

  email-relay -h "smtp.mail.yahoo.com" -rp "465" -s -u "$my_email" -p "$my_password" -f "$my_email"

Real-World Example for GMX Mail:

documentation for connecting to remote SMTP server: | | | |----------|--------------------------------------------------| | hostname | mail.gmx.com | | port | 465 (SSL or TLS) or 587 (STARTTLS or encryption) | | secure | false or true | | username | me@gmx.com | | password | my-website-login-password |

<options>:

  my_email='me@gmx.com'
  my_password='my-website-login-password'

  email-relay -h "mail.gmx.com" -rp "465" -s -u "$my_email" -p "$my_password" -f "$my_email"

Real-World Example for Zoho Mail:

documentation for connecting to remote SMTP server: | | | |----------|---------------------------| | hostname | smtp.zoho.com | | port | 465 (SSL) or 587 (TLS) | | secure | true | | username | me@zohomail.com | | password | my-website-login-password |

<options>:

  my_email='me@zohomail.com'
  my_password='my-website-login-password'

  email-relay -h "smtp.zoho.com" -rp "465" -s -u "$my_email" -p "$my_password" -f "$my_email"

Etc:

The following command-line SMTP clients are worthy of a mention. They provide an easy way to send messages to a running instance of email-relay.

blat

platforms: Windows

example of usage:

  rem :: a value for the "from" sender is required,
  rem :: but "email-relay" is configured to override this value.
  set email_from=me@example.com

  set email_to=me@gmail.com
  set subject=Test: blat
  set body=Hello, SMTPd!
  set smtpd_host=localhost
  set smtpd_port=25

  blat.exe -f "%email_from%" -to "%email_to%" -subject "%subject%" -body "%body%" -server "%smtpd_host%:%smtpd_port%"

tested with: v3.22.4 for Win64

mailsend-go

platforms: Windows, Linux, MacOS, Raspberry pi

example of usage:

  rem :: a value for the "from" sender is required,
  rem :: but "email-relay" is configured to override this value.
  set email_from=me@example.com

  set email_to=me@gmail.com
  set subject=Test: mailsend-go
  set body=Hello, SMTPd!
  set smtpd_host=localhost
  set smtpd_port=25

  mailsend-go.exe -f "%email_from%" -t "%email_to%" -sub "%subject%" body -msg "%body%" -smtp "%smtpd_host%" -port "%smtpd_port%"

tested with: v1.0.10 for Win64

Credits:

Nodemailer does absolutely all of the heavy lifting required by this project:

smtp-server creates the local SMTP server
mailparser reads messages received by the local SMTP server and parses them to a standardized data structure
nodemailer sends messages received by the local SMTP server (and optionally modified by middleware) to the remote SMTP server

Legal:

copyright: Warren Bank
license: GPL-2.0

email SMTP relay proxy

@warren-bank/node-process-argv mailparser nodemailer smtp-server

@everything-registry/sub-chunk-1000

1.0.1

8 months ago

1.0.0

8 months ago