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 | [email protected] | | password | my-generated-app-password |
• account page to generate a Yahoo Mail app password:
  • Account Security > Generate app password
• <options>:

    my_email='[email protected]'
    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 | [email protected] | | password | my-website-login-password |
• <options>:

    my_email='[email protected]'
    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 | [email protected] | | password | my-website-login-password |
• <options>:

    my_email='[email protected]'
    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.

1. 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 protected]
     
       set [email protected]
       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
2. 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 protected]
     
       set [email protected]
       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
  • documentation
  • npm
  • git repo
• mailparser reads messages received by the local SMTP server and parses them to a standardized data structure
  • documentation
  • npm
  • git repo
• nodemailer sends messages received by the local SMTP server (and optionally modified by middleware) to the remote SMTP server
  • documentation
  • npm
  • git repo

Legal:

• copyright: Warren Bank
• license: GPL-2.0