https://github.com/mono-js/mono-mail
Mails module for mono
https://github.com/mono-js/mono-mail
mail mono mono-module
Last synced: 2 months ago
JSON representation
Mails module for mono
- Host: GitHub
- URL: https://github.com/mono-js/mono-mail
- Owner: mono-js
- License: mit
- Created: 2018-03-05T09:48:11.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-08-20T23:19:26.000Z (almost 7 years ago)
- Last Synced: 2025-04-01T13:51:14.563Z (3 months ago)
- Topics: mail, mono, mono-module
- Language: JavaScript
- Size: 180 KB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
> Emails module for [Mono](https://github.com/terrajs/mono)
[](https://www.npmjs.com/package/mono-mail)
[](https://travis-ci.org/terrajs/mono-mail)
[](https://codecov.io/gh/terrajs/mono-mail.js)
[](https://github.com/terrajs/mono-mail/blob/master/LICENSE)
## Installation
```bash
npm install --save mono-mail
```
Then, in your configuration file of your Mono application (example: `conf/application.js`):
```js
module.exports = {
mono: {
modules: ['mono-mail']
}
}
```
## Configuration
`mono-mail` will use the `mono.mail` property of your configuration (example: `conf/development.js`):
```js
module.exports = {
mono: {
mail: {
// Optional, if not provided, only preview will be available
provider: {
name: 'smtp || ses',
... // Provider conf
},
// Sender email adress (required)
from: '[email protected]',
// Enabled by default on development
exposeRoutes: true
}
}
}
```
## Providers
Mono mail is currently supporting two providers to send your email:
- SMTP provider, using [nodemailer](https://github.com/nodemailer/nodemailer) with the [nodemailer-smtp-transport](https://github.com/nodemailer/nodemailer-smtp-transport) transport
- [SES](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SES.html) Amazon, using [nodemail](https://github.com/nodemailer/nodemailer) with the [nodemailer-ses-transport](https://github.com/nodemailer/nodemailer-ses-transport) transport.
If no provider is provided the library will remove the `/mails/send` route and the [send](#send) method.
## Usage
Mono mail is a mono module that using [mjml](https://mjml.io) and [handlebar](https://handlebarsjs.com) to generate and send awesome mails.
```js
const monoMail = require('mono-mail')
```
Mono mail also expose some methods as REST routes
TODO: All rest calls need a session and a role that contain `manageMail` action. This action is not added automatically.
## Routes
The routes for preview and sending an email are only available on development environment or if the `exposeRoutes` is set to true in the configuration of the module.
### Test preview route
Run the mono server with mono-mail:
```
NODE_ENV=test npx mono dev test/fixture/ok/
```
Once the server launched go to this [url](http://localhost:8000/mails/preview?data[title]=Welcome%20to%20mono-mail&data[description]=Mono%20mail%20is%20a%20mono%20module%20that%20using%20mjml%20and%20handlebar%20to%20generate%20and%20send%20awesome%20mails.&path=test/fixtures/ok/email-preview.html)
### Roadmap
- Add attachment MINE Type in HTTP `POST` route
### Exposed routes
| Method | URI | Query params | Body | Action |
| :------| :---| :------------| :-----| :--------|
| `GET` | /mails/preview | `path`, `data`, `pathType` | | Return HTML Generated mail |
| `POST` | /mails/send | `pathType` | `path`, `data`, `to`, `subject` | Send email |
Query params:
- `pathType`?: String (`relative` or `absolute`) Relative from current mono instance __dirname__
Post/Query params:
- `path`: String. Path to the mail file
- `data`: Object. Data object that will be compiled by handlebar
Post params:
- `subject`: String (compiled with handlebar). Subject of the mail
- `to`: String. Email adress of the sender
## Methods
### registerPartial
```js
registerPartial(partialName = String, partialPathmail = String): Promise
```
Register new partial template to be used inside mail template
Arguments:
- `partialName`: String. Partial name key
- `partialPathmail`: String. Path of the partial template
```js
// Register new partial
const template = await monoMail.registerPartial('font-footer', join(__dirname, 'modules/mails/font-footer.html'))
```
### generate
```js
generate(mail = { path, data, subject }): Promise
```
Generate HTML template from mail object.
Arguments:
- `path`: String. Path to the mail file
- `data`: Object. Data object that will be compiled by handlebar
- `subject`: String (compiled with handlebar). Subject of the mail
```js
// Generate template mail in HTML
const template = await monoMail.generate({
subject: 'Hello, {{ firstName }}',
path: join(__dirname, 'modules/users/signup.html'),
data: {
title: 'Welcome to mono-mail',
description: 'Mono module using mjml and handlebar to generate awesome template mail and send it to your customers'
}
})
```
### send
```js
send(mail = { path, data, subject, bcc, to, attachments: [{ filename, path, contentType }] }): Promise
```
Generate HTML template from mail object.
Arguments:
- `bcc`: String. Blind Carbon Copy email
- `to`: String. Recipient email address
- `attachments`: Array<{ filename, path, contentType }>. Attachment to the mail
```js
// Send email to [email protected] recipient
const template = await monoMail.generate({
subject: 'Hello, {{ firstName }}',
path: join(__dirname, 'modules/users/signup.html'),
bcc: '[email protected]',
to: '[email protected]',
data: {
title: 'Welcome to mono-mail',
description: 'Mono module using mjml and handlebar to generate awesome template mail and send it to your customers'
}
})
```
## Development / Contribution
See the [contribution guidelines](CONTRIBUTING.md) of this project.
## License
MIT © gaetansenn