postal-mailer

Mailer engine using mjml templates to send mail via postal api or smtp

Features

• configure inline (json object) or by dotenv
• uses handlebars + mjml for compilation and render
• sends mails via postal api or smtp

Install

$ yarn add @uscreen.de/postal-mailer # or use npm -i

Example

const mailer = require('@uscreen.de/postal-mailer')({
  // load config defaults from .env file (defaults to false)
  useDotenv: true,

  // override with inline options if needed
  postalSender: '[email protected]'
})

const result = await mailer
  .sendMail({
    data,
    template: 'test',
    to: '[email protected]',
    subject: 'Example Test Mail'
  })
  .then(r => {
    console.log('RESULT:', r)
  })
  .catch(e => {
    console.error('ERROR sending mail:', e)
  })

Template

Please refer to https://mjml.io and https://handlebarsjs.com. Start with example like so:

<mjml>
  <mj-head>
    <mj-title>Test Mail</mj-title>
    <mj-attributes>
      <mj-all font-family="BlinkMacSystemFont, -apple-system, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif;"></mj-all>
      <mj-text font-weight="300" font-size="16px" color="#000000" line-height="24px"></mj-text>
    </mj-attributes>
  </mj-head>

  <mj-body background-color="#F2F2F2">

    <mj-section background-color="#ff781e" padding="20px">
      <mj-column width="100%">
        <mj-text align="center" font-size="24px" color="#ffffff" font-weight="600">
          A very simple Test E-Mail
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-section background-color="#FFFFFF" padding="40px 20px">
      <mj-column width="100%">
        <mj-text>
          Greetings {{user.firstName}} {{user.lastName}},<br>
          <br>
          this is a simple example on how to setup a template and pass in some data.
        </mj-text>
        <mj-text>
          template will prefix all asset urls (ie. imgages) with<br>"{{postalAssetsUrl}}"
        </mj-text>
      </mj-column>
    </mj-section>

    <mj-section padding="0px 0 20px 0">
      <mj-column>
        <mj-text align="center" color="#9B9B9B" font-size="11px">ACME Inc, Street. 1, 12345 City</mj-text>
      </mj-column>
    </mj-section>

  </mj-body>
</mjml>

which renders to something like this:

Options

All options can be managed via .env file and/or inline configuration as seen above. Overview of options:

| option | Description | Default | Example | |-------------------------|-------------------------------------------------------------------------------------------------------------|-------------------|-------------------------------------| | useDotenv | whether to also read options from .env files | false | true | | postalTransport | Send mail via Postal API or SMTP | postal | smtp | | postalServer | Postal Server Host | | postal.example.com | | postalPort | If sending via SMTP, the SMTP port | 25 | 25 | | postalUser | If sending via SMTP, the SMTP username | | acme/my-api | | postalKey | If sending via Postal API, the API Key to use. If sending via SMTP, the SMTP password | | ExAmPlE_key | | postalSender | From Address in emails | | [email protected] | | postalTemplates | path to directory containing email templates | <cwd>/templates | ./templates/mails | | postalAssetsUrl | url to prefix assets | '' | https://www.example.com/mail/assets | | postalDefaultLocale | when set, locales will default to 'en' and templates will default ./templates/en instead of ./templates | '' | 'en' |

API

mailer.sendMail({ template, data, to, subject, locale = '' })

Send a template rendered with data to a recepient with a subject. (In an optional language set by locale)

Roadmap

• use esm (or shim with https://github.com/standard-things/esm)
• upgrades: ◯ globby latest 11.0.4 ❯ 12.0.2 https://github.com/sindresorhus/globby#readme
• deplrecate postalAssetsUrl as this is implementation context

Changelog

0.6.0

• added smtp example
• fixed pending upgrades

0.5.0

• added support of attachments
• added smtp transport

0.2.0

• added (optional) multilanguage support for templates
• added examples and docs

0.1.0

• rendering of templates (to html + text) & sending thru api works