Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/clevertech/email-service
Email microservice that sends emails based on templates
https://github.com/clevertech/email-service
email i18n microservice template
Last synced: 3 months ago
JSON representation
Email microservice that sends emails based on templates
- Host: GitHub
- URL: https://github.com/clevertech/email-service
- Owner: clevertech
- Created: 2017-02-27T15:05:53.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-05-28T16:24:36.000Z (over 6 years ago)
- Last Synced: 2024-04-26T16:46:09.893Z (7 months ago)
- Topics: email, i18n, microservice, template
- Language: HTML
- Homepage:
- Size: 79.1 KB
- Stars: 75
- Watchers: 10
- Forks: 24
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-list-microservice - email-service
README
# Email service
Email microservice that sends emails based on templates. Can be used as a standalone web service or as an express router.
## Running as a command line application
The npm package configures an `pnp-email-service` executable. You will pass configuration options
through ENV variables. Check the configuration options below.
## Running as a standalone HTTP server via API
This 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.
```javascript
const emailService = require('pnp-email-service')
const config = {
/* Check the configuration options below */
}
const server = emailService.startServer(config, () => {
const port = server.address().port
console.log(`Listening on port ${port}! Send an HTTP POST to http://127.0.0.1:${port}/email/send for sending an email`)
})
```
## Running as an express router
```javascript
const emailService = require('pnp-email-service')
const config = {
/* Check the configuration options below */
}
const router = emailService.createRouter(config)
app.use('/email', router)
```
## Invoking
Invoking 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`.
You need to send a JSON body with the following structure:
```javascript
{
"language": "en",
"templateName": "welcome",
"templateOptions": {
"user": {
"name": "John"
}
},
"emailOptions": {
"from": "Judy ",
"to": "John "
}
}
```
If your `{lang}/{templateName}-body-html.ejs` template has this content:
```html
h1 { color: #777 }
Welcome <%= user.name %>
Cheers,
```
This HTML content will be sent:
```html
Welcome John
Cheers,
```
### Full example
The following code uses `node-fetch` as HTTP client library. It spins an HTTP server and provides a simple `sendEmail()` function:
```javascript
const fetch = require('node-fetch')
const emailService = require('pnp-email-service')
const emailServer = emailService.startServer(config)
const sendEmail = (templateName, emailOptions, templateOptions, language) => {
const port = emailServer.address().port
const url = `http://127.0.0.1:${port}/email/send`
const body = { templateName, emailOptions, templateOptions, language }
return fetch(url, {
method: 'POST',
body: JSON.stringify(body),
headers: { 'Content-Type': 'application/json' }
})
}
// Example usage passing a `user` object to the template
sendEmail('welcome', { to: email }, { user })
.then(response => console.log('Email sent'))
.catch(err => console.error(err.stack))
```
## Configuration options
All 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:
- `EMAIL_DEFAULT_FROM` parameter passed to `createRouter()` or `startServer()`
- `DEFAULT_FROM` parameter passed to `createRouter()` or `startServer()`
- `EMAIL_DEFAULT_FROM` ENV variable
- `DEFAULT_FROM` ENV variable
This is the list of available configuration options:
| Variable | Description |
| --- | --- |
| `MICROSERVICE_PORT` | Port number for the standalone application. If not specified it will run in a random port |
| `DEFAULT_FROM` | Default email sender if a `from` parameter is not specified |
| `DEFAULT_LANGUAGE` | Default language to be used if a `language` is not specified. Defaults to `en` |
| `TRANSPORT` | Third-party service to be used to send the email. Supported values: [`ses`, `sendgrid`, `postmark`, `mailgun`, 'smtp'] for production; `stub` for testing |
| `AWS_KEY` | AWS Key for sending emails using Amazon SES |
| `AWS_SECRET` | AWS Secret for sending emails using Amazon SES |
| `AWS_REGION` | AWS Region for sending emails using Amazon SES |
| `SENDGRID_API_KEY` | API Key for sending emails when using Sendgrid |
| `POSTMARK_API_KEY` | API Key for sending emails when using Postmark |
| `MAILGUN_API_KEY` | API Key for sending emails when using Mailgun |
| `MAILGUN_DOMAIN` | Domain name from which emails are sent when using Mailgun |
| `SMTP_HOST` | SMTP host from which emails are sent when using SMTP |
| `SMTP_PORT` | SMTP port from which emails are sent when using SMTP |
| `SMTP_SECURE` | SMTP TLS from which emails are sent when using SMTP ("true"/"false") |
| `SMTP_USER` | SMTP user from which emails are sent when using SMTP |
| `SMTP_PASS` | SMTP password from which emails are sent when using SMTP |
| `TEMPLATES_DIR` | Absolute path to directory where templates will be found |
## Templates
The service will use the following templates:
- `{lang}/{templateName}-body-text.ejs` if available it will be used as plain text version of the message
- `{lang}/{templateName}-subject.ejs` for the email subject
For the HTML body one of these will be used:
- `{lang}/{templateName}-body-html.ejs` HTML template using [EJS](http://ejs.co)
- `{lang}/{templateName}-body-html.pug` HTML template using [PUG](https://pugjs.org)
The HTML output of the template is passed through [juice](https://github.com/Automattic/juice) for inlining the CSS styles.
## Example templates
There are a few example templates available in the `example_templates` directory of the repo.
## Testing your templates
You can test your templates from the command line using tools such as [ejs-cli](https://www.npmjs.com/package/ejs-cli). For example:
```bash
ejs-cli example_templates/en/password_reset-body-html.ejs -O '{"name":"John","action_url":"http://","operating_system":"","browser_name":"","supp
ort_url":""}' > password_reset.html
```
Or 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.