https://github.com/steve-lebleu/cliam
Agnostic transactional email sending in Node.js environment
https://github.com/steve-lebleu/cliam
brevo email email-sender emails mailersend mailgun mailjet mandrill node nodemailer postmark sendgrid sendinblue smtp sparkpost transactional-emails wrapper
Last synced: about 1 month ago
JSON representation
Agnostic transactional email sending in Node.js environment
- Host: GitHub
- URL: https://github.com/steve-lebleu/cliam
- Owner: steve-lebleu
- License: agpl-3.0
- Created: 2021-03-18T00:52:30.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-22T07:02:09.000Z (about 1 year ago)
- Last Synced: 2025-03-17T04:43:06.833Z (about 1 month ago)
- Topics: brevo, email, email-sender, emails, mailersend, mailgun, mailjet, mandrill, node, nodemailer, postmark, sendgrid, sendinblue, smtp, sparkpost, transactional-emails, wrapper
- Language: TypeScript
- Homepage:
- Size: 8.47 MB
- Stars: 16
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://coveralls.io/github/steve-lebleu/cliam?branch=main)
[](https://www.codefactor.io/repository/github/steve-lebleu/cliam)
[](https://opensource.org/licenses/gpl-license.php)
# 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](https://github.com/steve-lebleu/cliam/wiki/Email-payload), one [output](https://github.com/steve-lebleu/cliam/wiki/Email-response).
- Multiple simultaneous transporters.
- [Configuration](https://github.com/steve-lebleu/cliam/wiki/Configuration-with-cliamrc.js) based, not implementation based : easy switch between different modes.
- Normalized [transactions events](https://github.com/steve-lebleu/cliam/wiki/Transactions).
- Securized payloads.
- Customisable default templates.
## > Table of contents
- [Requirements](#requirements)
- [Getting started](#getting-started)
- [Beneficiary use cases](#beneficiary-use-cases)
- [Supported web API providers](#supported-web-api-providers)
- [Licence](#licence)
- [Documentation](https://github.com/steve-lebleu/cliam/wiki)
> Requirements
- Node.js >= 18.19.0
- NPM >= 10.2.3
> Getting started
### Install
```shell
> npm i cliam --save
```
### Configure
Create a *.cliamrc.js* module on the root of your project.
```shell
> touch .cliamrc.js
```
Define a minimalist configuration in *.cliamrc.js* newly created:
```javascript
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](https://github.com/steve-lebleu/cliam/wiki/Configuration-with-cliamrc.js) wiki section for more information about availables options and configurations.
### Implement
```javascript
import { Cliam } from 'cliam';
// Do some stuffs ...
const payload = {
meta: {
from: { email: '[email protected]' },
to: [
{ email: '[email protected]' }
],
replyTo: { email: '[email protected]' },
subject: 'Welcome John'
}
content: [
{
type: 'text/html',
value: '
Hello Yoda
I use Cliam to send my emails !
'
}
]
};
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](https://github.com/steve-lebleu/cliam/wiki/Email-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 ?**
Your implementation does not move, you just have to adapt a configuration file, remove your legacy code and implement some 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 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 !**
No more, you can fallback easily with a one shot default template.
**:white_check_mark: 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](https://github.com/steve-lebleu/cliam/blob/main/LICENSE)