@unitybase/mailer

The module for sending and receiving mail.

Troubleshooting

Mail server connectivity can be verified using curl

# for SSL (`fullSSL: true` in ubConfig)
curl -vvv --ssl smtps://smtp-relay.gmail.com --mail-from my_email@adress.com  --mail-rcpt recipient@gmail.com --upload-file email.txt --user 'emailServerUserName:password'
# without SSL (`fullSSL: false` in ubConfig)
curl -vvv smtp://non-ssl.relay.com --mail-from my_email@adress.com  --mail-rcpt recipient@gmail.com --upload-file email.txt --user 'emailServerUserName:password'

or using ubcli mail command - this command takes mail server parameters from config

cd /opt/unitybase/product/my-product
strace -f -e trace=network ubcli mail --mail-rcpt "recipient@gmail.com" -env /var/opt/unitybase/my-app/ubConfig.env

In case of SSL routines::wrong version number error change the SMTP port from "587" to "465"

SSL/TLS notes

For SSL support OpenSSL libraries version >= 3 must be installed:

• Windows: libssl-3-x64.dll, libcrypto-3-x64.dll must be in the PATH
• Linux: libssl.so.3 libcrypto.so.3 must be in LD_LIBRARY_PATH. On Debian:

If UB server version >= 5.23.11 no additional step is required (openssl3 is in ub server dependencies), otherwise

// Ubuntu 22.04 | Debian
sudo apt install libssl3
 
// Oracle Enterprise linux 8.x
// add EPEL repo (if not lready added)
sudo dnf install oracle-epel-release-el8
// install OpenSSL3
sudo dnf install openssl3-libs

// Oracle Enterprise linux 9.x
sudo dnf install openssl3-libs

There is 2 property for SSL configuration:

• if tls: true: initial TCP connection established without a TLS. In case server protocol request to upgrade (usually after first handshake command) - connection upgraded to TLS;
• if fullSSL: true: initial TCP connection established with TLS (TSL/SSL tunnel), so any protocol commands send over TLS

Mailer availability warning

WARNING - do not send the mail directly from the HTTP thread. Mail server can fail or work slowly. The right way is to put the mail messages in the queue and send them via the scheduler.

@unitybase/ubq module already has:

• a module 'modules/mail-queue` for adding e-mails to the queue
• a mail scheduler job for sending mails from the queue (once a minute by default)

Usage sample

Direct mail sending (not recommended - use ubq and schedulers instead)

  const UBMail = require('@unitybase/mailer')
  // send e-mail
  let sender = new UBMail.TubMailSender({
    host: 'mail.host.name',
    port: '25',
    tls: false
  })
  sender.sendMail({
    subject: 'subject 1',
    bodyType: UBMail.TubSendMailBodyType.Text,
    body: 'body\r\n 1',
    fromAddr: mailAddr1,
    toAddr: [mailAddr1, mailAddr2]
  })

  // Receive e-mails
  let receiver = new UBMail.TubMailReceiver({
    host: mailHost,
    port: '110',
    tls: false,
    auth: true,
    user: 'mpv',
    password: 'myPassword'
  })
  receiver.reconnect();
  let cnt = r.getMessagesCount()
  let res = []
  for (let i = 1; i <= cnt; i++ ) {
      res.push(r.receive(i))
  }

GMail mailer params

Example of GMail mailer config parameters:

{
   "host": "smtp.gmail.com",
   "port": "587",
   "fromAddr": "......@gmail.com",
   "user": ".....@gmail.com",
   "password": "......",
   "fullSSL": true,
   "auth": true
}

Envs

UB_SMTP_HOST=smtp.gmail.com
UB_SMTP_PORT=587
UB_SMTP_PWD=....
UB_SMTP_AUTH=true
UB_SMTP_FULL_SSL=true
UB_SMTP_TLS=false

Office365 parameters

Env

UB_SMTP_HOST=smtp.office365.com
UB_SMTP_PORT=587
UB_SMTP_PWD=.....
UB_SMTP_AUTH=true
UB_SMTP_FULL_SSL=false
UB_SMTP_TLS=true