Skip to content

Latest commit

 

History

History
149 lines (112 loc) · 6.14 KB

README.md

File metadata and controls

149 lines (112 loc) · 6.14 KB
Raw

postal-mailer

Test CI Test Coverage Known Vulnerabilities NPM Version

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

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