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:

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

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