README
Transactional emails with a kick
Agnostic transactional email sending in Node.js environment :boom: :muscle: :pill:
> 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.
- Configuration based, not implementation based : easy switch between different modes.
- Normalized transactions events.
- Securized payloads.
- Customisable default templates.
> Table of contents
> Requirements
- Node.js >= 14.16.0
- NPM >= 6.14.11
> Getting started
Install
> npm i cliam --save
Configure
Create a .cliamrc.json file on the root of your project.
> touch .cliamrc.json
Define a minimalist configuration in .cliamrc.json newly created:
{
"consumer": {
"domain": "https://www.john-doe.com"
},
"mode": {
"api": {
"name": "YOUR_PROVIDER",
"credentials": {
"apiKey": "YOUR_API_KEY"
},
"templates" : {
"user.confirm": "TEMPLATE_ID_THAT_YOU_WILL_ASSOCIATE_TO_EVENT",
"...": "..."
}
}
}
}
See configuration wiki section for more information about availables options and configurations.
Implement
import { Cliam } from 'cliam';
// Do some stuffs ...
Cliam.emit('user.confirm', payload)
.then(res => {
console.log('Email has been delivered: ', res);
})
.catch(err => {
console.log('Error while mail sending: ', err)
});
See request payload wiki section for more information about availables options and configurations.
> Beneficiary use cases
:white_check_mark: 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.
:white_check_mark: I wish change from supplier, but I'm in panic about the implementation ?
Piece of cake, your implementation does not move, you just have to adapt a configuration file, remove your legacy code and implement some other lines of code.
:white_check_mark: 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 customisable templates. When your business is up, you can use a paid web api.
:white_check_mark: I did not have time to prepare the template for an important email that should be send today !
[Coming soon] No more, you can fallback easily with an one shot default template in two minutes, watch in hand.
:white_check_mark: I have a big problem with a provider, and my emails stay blocked in the pipe !
[Coming soon] The same: fallback on a SMTP server. In two minutes you're ready and your mailing is back in operation.
> Supported web API providers
