{"id":16203715,"url":"https://github.com/steve-lebleu/cliam","last_synced_at":"2025-08-23T15:03:25.625Z","repository":{"id":44879930,"uuid":"348896055","full_name":"steve-lebleu/cliam","owner":"steve-lebleu","description":"Agnostic transactional email sending in Node.js environment","archived":false,"fork":false,"pushed_at":"2024-03-22T07:02:09.000Z","size":8882,"stargazers_count":16,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-20T07:19:07.544Z","etag":null,"topics":["brevo","email","email-sender","emails","mailersend","mailgun","mailjet","mandrill","node","nodemailer","postmark","sendgrid","sendinblue","smtp","sparkpost","transactional-emails","wrapper"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steve-lebleu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"stevelebleu","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2021-03-18T00:52:30.000Z","updated_at":"2024-10-19T15:26:52.000Z","dependencies_parsed_at":"2023-12-20T20:25:13.582Z","dependency_job_id":"13465f80-e768-4255-bad7-680fe1114b20","html_url":"https://github.com/steve-lebleu/cliam","commit_stats":{"total_commits":103,"total_committers":3,"mean_commits":"34.333333333333336","dds":0.03883495145631066,"last_synced_commit":"d7668d60bd6daa42db4b1ef1ed16fed4cde1af45"},"previous_names":["steve-lebleu/cliam"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Fcliam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Fcliam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Fcliam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Fcliam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steve-lebleu","download_url":"https://codeload.github.com/steve-lebleu/cliam/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Fcliam/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259053511,"owners_count":22798438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brevo","email","email-sender","emails","mailersend","mailgun","mailjet","mandrill","node","nodemailer","postmark","sendgrid","sendinblue","smtp","sparkpost","transactional-emails","wrapper"],"created_at":"2024-10-10T09:54:52.741Z","updated_at":"2025-06-10T10:07:45.440Z","avatar_url":"https://github.com/steve-lebleu.png","language":"TypeScript","funding_links":["https://ko-fi.com/stevelebleu"],"categories":[],"sub_categories":[],"readme":"![Cliam](https://cdn.konfer.be/images/cliam/assets/banner-cliam.png)\n\n![Github action workflow status](https://github.com/steve-lebleu/cliam/actions/workflows/build.yml/badge.svg?branch=main)\n[![Coverage Status](https://coveralls.io/repos/github/steve-lebleu/cliam/badge.svg?branch=main)](https://coveralls.io/github/steve-lebleu/cliam?branch=main)\n[![CodeFactor](https://www.codefactor.io/repository/github/steve-lebleu/cliam/badge)](https://www.codefactor.io/repository/github/steve-lebleu/cliam)\n![GitHub Release](https://img.shields.io/github/v/release/steve-lebleu/cliam?logo=Github)\n[![GPL Licence](https://badges.frapsoft.com/os/gpl/gpl.svg?v=103)](https://opensource.org/licenses/gpl-license.php)\n\n# Transactional emails with a kick\n\nAgnostic transactional email sending in Node.js environment :boom: :muscle: :pill:\n\n## \u003e Why ?\n\nTo improve and facilitate the implementation, flexibility and maintenance of transactional emailing tasks.\n\n## \u003e Features\n\n- 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).\n- Multiple simultaneous transporters.\n- [Configuration](https://github.com/steve-lebleu/cliam/wiki/Configuration-with-cliamrc.js) based, not implementation based : easy switch between different modes.\n- Normalized [transactions events](https://github.com/steve-lebleu/cliam/wiki/Transactions).\n- Securized payloads.\n- Customisable default templates.\n\n## \u003e Table of contents\n\n- [Requirements](#requirements)\n- [Getting started](#getting-started)\n- [Beneficiary use cases](#beneficiary-use-cases)\n- [Supported web API providers](#supported-web-api-providers)\n- [Licence](#licence)\n- [Documentation](https://github.com/steve-lebleu/cliam/wiki)\n\n\u003ch2 id=\"requirements\"\u003e\u003e Requirements\u003c/h2\u003e\n\n- Node.js \u003e= 18.19.0\n- NPM \u003e= 10.2.3\n\n\u003ch2 id=\"getting-started\"\u003e\u003e Getting started\u003c/h2\u003e\n\n### Install\n\n```shell\n\u003e npm i cliam --save\n```\n\n### Configure\n\nCreate a *.cliamrc.js* module on the root of your project.\n\n```shell\n\u003e touch .cliamrc.js\n```\n\nDefine a minimalist configuration in *.cliamrc.js* newly created:\n\n```javascript\nmodule.exports = {\n  \"sandbox\": true,\n  \"transporters\": [\n    {\n      \"id\": \"unique-transporter-key\",\n      \"auth\": {\n        \"username\": process.env.SMTP_USERNAME,\n        \"password\": process.env.SMTP_PWD\n      },\n      \"options\": {\n        \"host\": process.env.SMTP_HOST,\n        \"port\": 587,\n        \"secure\": false\n      }\n    },\n    {\n      \"id\": \"other-unique-transporter-key\",\n      \"provider\": \"sendgrid\",\n      \"auth\": {\n        \"apiKey\": process.env.WEB_API_SENDGRID_API_KEY,\n      },\n      \"templates\": {\n        \"user.welcome\": \"d-321bb40f548e4db8a628b4d6464ebacc\",\n        ...\n      }\n    }\n  ]\n}\n```\n\nIt'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.\n\nSee [cliamrc configuration](https://github.com/steve-lebleu/cliam/wiki/Configuration-with-cliamrc.js) wiki section for more information about availables options and configurations.\n\n### Implement\n\n```javascript\nimport { Cliam } from 'cliam';\n\n// Do some stuffs ...\n  \nconst payload = {\n  meta: {\n    from: { email: 'john.doe@hotmail.com' },\n    to: [\n      { email: 'john.allan.poe@hotmail.com' }\n    ],\n    replyTo: { email: 'john.doe@hotmail.com' },\n    subject: 'Welcome John'\n  }\n  content: [\n    {\n      type: 'text/html',\n      value: '\u003ch1\u003eHello Yoda\u003c/h1\u003e\u003cp\u003eI use Cliam to send my emails !\u003c/p\u003e'\n    }\n  ]\n};\n\nCliam.mail('user.welcome', payload)\n  .then(res =\u003e {\n    console.log('Email has been delivered: ', res);\n  })\n  .catch(err =\u003e {\n    console.log('Error while mail sending: ', err)\n  });\n```\n\nBy 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.\n\nSee [email payload](https://github.com/steve-lebleu/cliam/wiki/Email-payload) wiki section for more information about availables options and configurations.\n\n\u003ch2 id=\"beneficiary-use-cases\"\u003e\u003e Beneficiary use cases\u003c/h2\u003e\n\n**:white_check_mark: I have many projects which uses differents providers, it's a hell of a thing to maintain.**\n\nThis 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.\n\n**:white_check_mark: I wish change from supplier, but I'm in panic about the implementation ?**\n\nYour implementation does not move, you just have to adapt a configuration file, remove your legacy code and implement some lines of code. \n\n**:white_check_mark: I don't have a subscription to a supplier, and no templates**\n\nNo 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.\n\n**:white_check_mark: I did not have time to prepare the template for an important email that should be send today !**\n\nNo more, you can fallback easily with a one shot default template.\n\n**:white_check_mark: I have a big problem with a provider, and my emails stay blocked in the pipe !**\n\nThe same: fallback on a SMTP server. In two minutes you're ready and your mailing is back in operation.\n\n\u003ch2 id=\"supported-web-api-providers\"\u003e\u003e Supported web API providers\u003c/h2\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://sendgrid.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/sendgrid.png\" alt=\"Sendgrid\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://mailgun.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/mailgun.png\" alt=\"Mailgun\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://sparkpost.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/sparkpost.png\" alt=\"Sparkpost\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://postmarkapp.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/postmark.png\" alt=\"Postmark\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://mailjet.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/mailjet.png\" alt=\"Mailjet\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.sendinblue.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/sendinblue.png\" alt=\"Sendinblue\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://brevo.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/brevo.png\" alt=\"Brevo\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://app.mailersend.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/mailersend.png\" alt=\"Mailersend\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://mandrillapp.com/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/mandrill.png\" alt=\"Mandrill\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!--\n\u003cp\u003e\n  \u003ca href=\"https://aws.amazon.com/fr/ses/\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.konfer.be/images/cliam/providers/amazon-ses.png\" alt=\"Amazon SES\" width=\"240px\" hspace=\"15\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n--\u003e\n\n\u003ch2 id=\"licence\"\u003e\u003e Licence\u003c/h2\u003e\n\n[AGPL-3.0 License](https://github.com/steve-lebleu/cliam/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteve-lebleu%2Fcliam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteve-lebleu%2Fcliam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteve-lebleu%2Fcliam/lists"}