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 isTLSv1.2
- the
-
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:
- the
-
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