{"id":13753773,"url":"https://github.com/clevertech/email-service","last_synced_at":"2025-08-22T02:08:20.112Z","repository":{"id":57326494,"uuid":"83323234","full_name":"clevertech/email-service","owner":"clevertech","description":"Email microservice that sends emails based on templates","archived":false,"fork":false,"pushed_at":"2018-05-28T16:24:36.000Z","size":81,"stargazers_count":74,"open_issues_count":4,"forks_count":25,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-08-18T02:41:40.470Z","etag":null,"topics":["email","i18n","microservice","template"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clevertech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-27T15:05:53.000Z","updated_at":"2024-11-12T01:01:18.000Z","dependencies_parsed_at":"2022-09-21T02:01:15.826Z","dependency_job_id":null,"html_url":"https://github.com/clevertech/email-service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/clevertech/email-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Femail-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Femail-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Femail-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Femail-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clevertech","download_url":"https://codeload.github.com/clevertech/email-service/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Femail-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271574431,"owners_count":24783319,"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","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["email","i18n","microservice","template"],"created_at":"2024-08-03T09:01:29.219Z","updated_at":"2025-08-22T02:08:20.085Z","avatar_url":"https://github.com/clevertech.png","language":"HTML","readme":"# Email service\n\nEmail microservice that sends emails based on templates. Can be used as a standalone web service or as an express router.\n\n## Running as a command line application\n\nThe npm package configures an `pnp-email-service` executable. You will pass configuration options\nthrough ENV variables. Check the configuration options below.\n\n## Running as a standalone HTTP server via API\n\nThis is the recommended method for running the microservice via API. You can ignore the `MICROSERVICE_PORT` configuration and this will spin up a server at a random port. Then you can obtain the port the server is running by calling `server.address().port`. This way the microservice is not exposed in the same port than your main application and you are sure it will run in an available port.\n\n```javascript\nconst emailService = require('pnp-email-service')\nconst config = {\n  /* Check the configuration options below */\n}\nconst server = emailService.startServer(config, () =\u003e {\n  const port = server.address().port\n  console.log(`Listening on port ${port}! Send an HTTP POST to http://127.0.0.1:${port}/email/send for sending an email`)\n})\n```\n\n## Running as an express router\n\n```javascript\nconst emailService = require('pnp-email-service')\nconst config = {\n  /* Check the configuration options below */\n}\nconst router = emailService.createRouter(config)\napp.use('/email', router)\n```\n\n## Invoking\n\nInvoking the service is as simple as doing an HTTP POST request to `{baseURL}/send`. The `baseURL` depends on how you are deploying the service. For example if you are running it as an express router mounted in `/email` in a server running at `127.0.0.1:3000` the URL will be: `http(s)://127.0.0.1:3000/email/send`.\n\nYou need to send a JSON body with the following structure:\n\n```javascript\n{\n  \"language\": \"en\",\n  \"templateName\": \"welcome\",\n  \"templateOptions\": {\n    \"user\": {\n      \"name\": \"John\"\n    }\n  },\n  \"emailOptions\": {\n    \"from\": \"Judy \u003cjudy@example.com\u003e\",\n    \"to\": \"John \u003cjohn@example.com\u003e\"\n  }\n}\n```\n\nIf your `{lang}/{templateName}-body-html.ejs` template has this content:\n\n```html\n\u003cstyle\u003e\n  h1 { color: #777 }\n\u003c/style\u003e\n\u003ch1\u003eWelcome \u003c%= user.name %\u003e\u003c/h1\u003e\n\u003cp\u003eCheers,\u003c/p\u003e\n```\n\nThis HTML content will be sent:\n\n```html\n\u003ch1 style=\"color: #777;\"\u003eWelcome John\u003c/h1\u003e\n\u003cp\u003eCheers,\u003c/p\u003e\n```\n\n### Full example\n\nThe following code uses `node-fetch` as HTTP client library. It spins an HTTP server and provides a simple `sendEmail()` function:\n\n```javascript\nconst fetch = require('node-fetch')\nconst emailService = require('pnp-email-service')\nconst emailServer = emailService.startServer(config)\n\nconst sendEmail = (templateName, emailOptions, templateOptions, language) =\u003e {\n  const port = emailServer.address().port\n  const url = `http://127.0.0.1:${port}/email/send`\n  const body = { templateName, emailOptions, templateOptions, language }\n  return fetch(url, {\n    method: 'POST',\n    body: JSON.stringify(body),\n    headers: { 'Content-Type': 'application/json' }\n  })\n}\n\n// Example usage passing a `user` object to the template\nsendEmail('welcome', { to: email }, { user })\n  .then(response =\u003e console.log('Email sent'))\n  .catch(err =\u003e console.error(err.stack))\n```\n\n## Configuration options\n\nAll configuration options can be configured using ENV variables. If using it as an express router, then configuration variables can also be passed as an argument to this method. All ENV variables can be prefixed with `EMAIL_`. Since one value can be configured in many ways some take precedence over others. For example for the `DEFAULT_FROM` variable the value used will be the first found following this list:\n\n- `EMAIL_DEFAULT_FROM` parameter passed to `createRouter()` or `startServer()`\n- `DEFAULT_FROM` parameter passed to `createRouter()` or `startServer()`\n- `EMAIL_DEFAULT_FROM` ENV variable\n- `DEFAULT_FROM` ENV variable\n\nThis is the list of available configuration options:\n\n| Variable | Description |\n| --- | --- |\n| `MICROSERVICE_PORT` | Port number for the standalone application. If not specified it will run in a random port |\n| `DEFAULT_FROM` | Default email sender if a `from` parameter is not specified |\n| `DEFAULT_LANGUAGE` | Default language to be used if a `language` is not specified. Defaults to `en` |\n| `TRANSPORT` | Third-party service to be used to send the email. Supported values: [`ses`, `sendgrid`, `postmark`, `mailgun`, 'smtp'] for production; `stub` for testing |\n| `AWS_KEY` | AWS Key for sending emails using Amazon SES |\n| `AWS_SECRET` | AWS Secret for sending emails using Amazon SES |\n| `AWS_REGION` | AWS Region for sending emails using Amazon SES |\n| `SENDGRID_API_KEY` | API Key for sending emails when using Sendgrid |\n| `POSTMARK_API_KEY` | API Key for sending emails when using Postmark |\n| `MAILGUN_API_KEY` | API Key for sending emails when using Mailgun |\n| `MAILGUN_DOMAIN` | Domain name from which emails are sent when using Mailgun |\n| `SMTP_HOST` | SMTP host from which emails are sent when using SMTP |\n| `SMTP_PORT` | SMTP port from which emails are sent when using SMTP |\n| `SMTP_SECURE` | SMTP TLS from which emails are sent when using SMTP (\"true\"/\"false\") |\n| `SMTP_USER` | SMTP user from which emails are sent when using SMTP |\n| `SMTP_PASS` | SMTP password from which emails are sent when using SMTP |\n| `TEMPLATES_DIR` | Absolute path to directory where templates will be found |\n\n## Templates\n\nThe service will use the following templates:\n\n- `{lang}/{templateName}-body-text.ejs` if available it will be used as plain text version of the message\n- `{lang}/{templateName}-subject.ejs` for the email subject\n\nFor the HTML body one of these will be used:\n\n- `{lang}/{templateName}-body-html.ejs` HTML template using [EJS](http://ejs.co)\n- `{lang}/{templateName}-body-html.pug` HTML template using [PUG](https://pugjs.org)\n\nThe HTML output of the template is passed through [juice](https://github.com/Automattic/juice) for inlining the CSS styles.\n\n## Example templates\n\nThere are a few example templates available in the `example_templates` directory of the repo.\n\n## Testing your templates\n\nYou can test your templates from the command line using tools such as [ejs-cli](https://www.npmjs.com/package/ejs-cli). For example:\n\n```bash\nejs-cli example_templates/en/password_reset-body-html.ejs -O '{\"name\":\"John\",\"action_url\":\"http://\",\"operating_system\":\"\",\"browser_name\":\"\",\"supp\nort_url\":\"\"}' \u003e password_reset.html\n```\n\nOr you can specify `TRANSPORT=stub`. This way no real emails will be sent and you will get the rendered templates as response when invoking the service.\n","funding_links":[],"categories":["template"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclevertech%2Femail-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclevertech%2Femail-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclevertech%2Femail-service/lists"}