Transactional emails with a kick

Agnostic transactional email sending in Node.js environment 💥 💪 💊

> Why ?

To improve and facilitate the implementation, flexibility and maintenance of transactional emailing tasks.

> Features

• Agnostic transactional email sending using web API or SMTP server. One input, one output.
• Multiple simultaneous transporters.
• Configuration based, not implementation based : easy switch between different modes.
• Normalized transactions events.
• Securized payloads.
• Customisable default templates.

> Table of contents

• Requirements
• Getting started
• Beneficiary use cases
• Supported web API providers
• Licence
• Documentation

> Requirements

• Node.js >= 18.19.0
• NPM >= 10.2.3

> Getting started

Install

> npm i cliam --save

Configure

Create a .cliamrc.js module on the root of your project.

> touch .cliamrc.js

Define a minimalist configuration in .cliamrc.js newly created:

module.exports = {
  "sandbox": true,
  "transporters": [
    {
      "id": "unique-transporter-key",
      "auth": {
        "username": process.env.SMTP_USERNAME,
        "password": process.env.SMTP_PWD
      },
      "options": {
        "host": process.env.SMTP_HOST,
        "port": 587,
        "secure": false
      }
    },
    {
      "id": "other-unique-transporter-key",
      "provider": "sendgrid",
      "auth": {
        "apiKey": process.env.WEB_API_SENDGRID_API_KEY,
      },
      "templates": {
        "user.welcome": "d-321bb40f548e4db8a628b4d6464ebacc",
        ...
      }
    }
  ]
}

It's advised to use environment secrets to fill in sensible values like api keys. Dotenv is embedded in Cliam, so you can just write an .env file with the required keys regarding your cliamrc.js definition.

See cliamrc configuration wiki section for more information about availables options and configurations.

Implement

import { Cliam } from 'cliam';

// Do some stuffs ...
  
const payload = {
  meta: {
    from: { email: 'john.doe@hotmail.com' },
    to: [
      { email: 'john.allan.poe@hotmail.com' }
    ],
    replyTo: { email: 'john.doe@hotmail.com' },
    subject: 'Welcome John'
  }
  content: [
    {
      type: 'text/html',
      value: '<h1>Hello Yoda</h1><p>I use Cliam to send my emails !</p>'
    }
  ]
};

Cliam.mail('user.welcome', payload)
  .then(res => {
    console.log('Email has been delivered: ', res);
  })
  .catch(err => {
    console.log('Error while mail sending: ', err)
  });

By default, Cliam will use the first transporter found in the cliamrc file, except if you precise wich transporterId you want to use on the fly.

See email payload wiki section for more information about availables options and configurations.

> Beneficiary use cases

✅ I have many projects which uses differents providers, it's a hell of a thing to maintain.

This is to be forgotten with Cliam. No more worries about polymorphics inputs / outputs. Whether you are working with an A, B, C, D provider or a smtp server, your input / output will always be the same regardless of your delivery method or service provider.

✅ I wish change from supplier, but I'm in panic about the implementation ?

Your implementation does not move, you just have to adapt a configuration file, remove your legacy code and implement some lines of code.

✅ I don't have a subscription to a supplier, and no templates

No problem, we have all been poor once. Start with a simple SMTP server and use default templates. When your business is up, you can use a paid web api.

✅ I did not have time to prepare the template for an important email that should be send today !

No more, you can fallback easily with a one shot default template.

✅ I have a big problem with a provider, and my emails stay blocked in the pipe !

The same: fallback on a SMTP server. In two minutes you're ready and your mailing is back in operation.

> Supported web API providers

> Licence

AGPL-3.0 License