@sapphirejs/mail

Mail

A fluent email sender built as a thin wrapper on top of nodemailer. It handles almost everything nodemailer does, but presents them in a more intuitive package. Actually supports STMP and SES transports, with plans to provide more in the future.

Usage

$ npm install --save @sapphirejs/mail

We'll start with an exhaustive example that includes pretty much every option.

const { Mail, Transport } = require('@sapphirejs/mail')

const config = { host: 'smtp.example.com' }
const mail = new Mail({}, new Transport.SMTP(config))
await mail.send('<p>Hi</p>', message => {
  message
    .from('[e-mail]')
    .replyTo('[e-mail]')
    .to('[e-mail]')
    .cc('[e-mail]')
    .bcc('[e-mail]')
    .subject('Testing')
    .attach({ filename: 'file.txt', content: 'File' })
    .header('my-key', '123')
    .alternative('text/x-web-markdown', '**Email body**')
    .priority('low')
})

HTML and Text Body

The first parameter of Mail.send() can be either a string as the HTML body, or an object that may set both the text and html versions. It is a good practice to include them both.

await mail.send({ html: '<p>Hi</p>', text: 'Hi' }, /* rest of the message */)

Global "from" Header

When the "from" header is passed as Mail's config, it will be automatically included in every mail instance. Off course it also be overriden with the from function.

const mail = new Mail({ from: '[e-mail]' }, new Transport.SMTP(config))

Name, Email Format

The from, replyTo, to, cc, and bcc headers can be set with a name followed by the email.

message
  .from('John Smith', '[e-mail]')
  .to('Jane Smith', '[e-mail]')

// or as a single parameter

message
  .from('John Smith <[e-mail]>')
  .to('Jane Smith <[e-mail]>')

Multiple Parameters

Multiple receivers, either to, cc, or bcc, can be chained to add more than one.

message
  .to('John Smith<[e-mail]>')
  .to('Jane Smith<[e-mail]>')

The same applies to header, attachment, and alternative.

Async

Mail.send() is an async function that returns a Promise and can be set to await. It will throw a MailSendingFailed if sending fails, or a MissingMailParams when the message headers aren't set correctly (ie: missing from field). Otherwise, it will return an info object with the details of the transport.

try {
  const mail = new Mail({}, new Transport.SMTP(config))
  const result = await mail
    .send('<p>Hello</p>', message => {
      message
        .from('[e-mail]')
        .to('[e-mail]')
        .subject('Testing')
    })
} catch(err) {
  // handle the error
}

SMTP Transport

The SMTP transport requires a configuration containing the server connection and authentication parameters. Most email services provide STMP options, so it should be a common transport for most use cases. A basic configuration is provided below, but you can read the nodemailer docs for more advanced options like pooled connections, certificates, etc.

const config = {
  host: 'smtp.thehost.com',
  port: 465,
  secure: false,
  auth: {
    user: 'user',
    pass: 'pass'
  }
}

const mail = new Mail({}, new Transport.SMTP(config))

SES Transport

The SES transport connects to the SES API, a very reliable and affordable mail service. Please refer to the AWS SDK docs for a list of configuration options, especially those in the section "Constructor Details".

const config = {{
  accessKeyId: 'ACCESS_KEY',
  secretAccessKey: 'SECRET_KEY',
  region: 'us-east-1'
}

const mail = new Mail({}, new Transport.SES(config))