@uscreen.de/postal-mailer NPM

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: 'domains+noreply@postal-stage.uscreen.net'
})

const result = await mailer
  .sendMail({
    data,
    template: 'test',
    to: 'rcpt@example.com',
    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:

npm.io

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		noreply@example.com
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