Naturally Produced Modules

    @sapphirejs/mail

    0.0.15 • Public • Published

    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('from@domain.com')
        .replyTo('from@domain.com')
        .to('to@domain.com')
        .cc('cc@domain.com')
        .bcc('bcc@domain.com')
        .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: 'from@domain.com' }, 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', 'from@domain.com')
      .to('Jane Smith', 'to@domain.com')
    
    // or as a single parameter
    
    message
      .from('John Smith <from@domain.com>')
      .to('Jane Smith <to@domain.com>')

    Multiple Parameters

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

    message
      .to('John Smith<from@domain.com>')
      .to('Jane Smith<to@domain.com>')

    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('from@domain.com')
            .to('to@domain.com')
            .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))

    Install

    npm i @sapphirejs/mail

    DownloadsWeekly Downloads

    0

    Version

    0.0.15

    License

    MIT

    Unpacked Size

    16.6 kB

    Total Files

    11

    Last publish

    Collaborators

    • aleksanderkoko
    • fadion