209 lines
6.8 KiB
Markdown
209 lines
6.8 KiB
Markdown
|
nodemailer-mailgun-transport
|
|||
|
============================
|
|||
|
[![Known Vulnerabilities](https://snyk.io/test/github/orliesaurus/nodemailer-mailgun-transport/badge.svg)](https://snyk.io/test/github/orliesaurus/nodemailer-mailgun-transport)
|
|||
|
|
|||
|
## What is this?
|
|||
|
nodemailer is an amazing node module to send emails within any of your nodejs apps.
|
|||
|
This is the transport plugin that goes with nodemailer to send email using [Mailgun](https://mailgun.com/)'s awesomeness!
|
|||
|
Pow Pow.
|
|||
|
|
|||
|
|
|||
|
## How does it work?
|
|||
|
Based on [this mailgun-js module](https://github.com/1lobby/mailgun-js) and the [nodemailer module](https://github.com/andris9/Nodemailer), the Mailgun Transport was born. This is a transport layer, meaning it will allow you to send emails using nodemailer, using the Mailgun API instead of the SMTP protocol!
|
|||
|
|
|||
|
Nodemailer allows you to write code once and then swap out the transport so you can use different accounts on different providers. On top of that it's a super solid way of sending emails quickly on your node app(s).
|
|||
|
|
|||
|
The Mailgun transport for nodemailer is great to use when SMTP is blocked on your server or you just prefer the reliability of the web api!
|
|||
|
|
|||
|
## Support the project
|
|||
|
I know this is a tiny module but many people use it in production (high5 to all of us) - if you happen to use this module please click the star button - it means a lot to all the contributors ![](https://i.snag.gy/oef5di.jpg)
|
|||
|
## Quickstart - Example
|
|||
|
|
|||
|
Create a new file, install the dependencies **[1]** and look at the skeleton code below to get you started quickly!
|
|||
|
|
|||
|
|
|||
|
```js
|
|||
|
const nodemailer = require('nodemailer');
|
|||
|
const mg = require('nodemailer-mailgun-transport');
|
|||
|
|
|||
|
// This is your API key that you retrieve from www.mailgun.com/cp (free up to 10K monthly emails)
|
|||
|
const auth = {
|
|||
|
auth: {
|
|||
|
api_key: 'key-1234123412341234',
|
|||
|
domain: 'one of your domain names listed at your https://app.mailgun.com/app/sending/domains'
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
const nodemailerMailgun = nodemailer.createTransport(mg(auth));
|
|||
|
|
|||
|
nodemailerMailgun.sendMail({
|
|||
|
from: 'myemail@example.com',
|
|||
|
to: 'recipient@domain.com', // An array if you have multiple recipients.
|
|||
|
cc:'second@domain.com',
|
|||
|
bcc:'secretagent@company.gov',
|
|||
|
subject: 'Hey you, awesome!',
|
|||
|
'replyTo': 'reply2this@company.com',
|
|||
|
//You can use "html:" to send HTML email content. It's magic!
|
|||
|
html: '<b>Wow Big powerful letters</b>',
|
|||
|
//You can use "text:" to send plain-text content. It's oldschool!
|
|||
|
text: 'Mailgun rocks, pow pow!'
|
|||
|
}, (err, info) => {
|
|||
|
if (err) {
|
|||
|
console.log(`Error: ${err}`);
|
|||
|
}
|
|||
|
else {
|
|||
|
console.log(`Response: ${info}`);
|
|||
|
}
|
|||
|
});
|
|||
|
```
|
|||
|
## Buffer support
|
|||
|
|
|||
|
Example:
|
|||
|
|
|||
|
```js
|
|||
|
const mailOptions = {
|
|||
|
...
|
|||
|
attachments: [
|
|||
|
{
|
|||
|
filename: 'text2.txt',
|
|||
|
content: new Buffer('hello world!','utf-8')
|
|||
|
},
|
|||
|
```
|
|||
|
|
|||
|
with encoded string as attachment content:
|
|||
|
|
|||
|
```js
|
|||
|
const mailOptions = {
|
|||
|
...
|
|||
|
attachments: [
|
|||
|
{
|
|||
|
filename: 'text1.txt',
|
|||
|
content: 'aGVsbG8gd29ybGQh',
|
|||
|
encoding: 'base64'
|
|||
|
},
|
|||
|
```
|
|||
|
|
|||
|
with encoded string as an inline attachment:
|
|||
|
|
|||
|
```js
|
|||
|
// Replace `filename` with `cid`
|
|||
|
const mailOptions = {
|
|||
|
...
|
|||
|
attachments: [
|
|||
|
{
|
|||
|
cid: 'logo.png',
|
|||
|
content: 'aGVsbG8gd29ybGQh',
|
|||
|
encoding: 'base64'
|
|||
|
},
|
|||
|
```
|
|||
|
```html
|
|||
|
<!-- Reference the `cid` in your email template file -->
|
|||
|
<img src="cid:logo.png" alt="logo" />
|
|||
|
```
|
|||
|
## Address objects
|
|||
|
The "from", "to", "cc", and "bcc" fields support an address object or array of address objects. Each "name" and "address" are converted to ```"name <address>"``` format. "name" is optional, "address" is required. Missing or null address in object is skipped.
|
|||
|
|
|||
|
Examples:
|
|||
|
```js
|
|||
|
from: {name: 'Sales', address: 'sales@example.com'},
|
|||
|
to: [{name:'Mary', address:'mary@differentexample.com'}, {address:'john@anotherexample.com'}]
|
|||
|
|
|||
|
```
|
|||
|
is converted to:
|
|||
|
```js
|
|||
|
from: 'Sales <sales@example.com>',
|
|||
|
to: 'Mary <mary@differentexample.com>,john@anotherexample.com'
|
|||
|
```
|
|||
|
## Now with Consolidate.js templates, and also compatible with mailgun's own templates
|
|||
|
|
|||
|
This package has two options for templating - one is to allow mailgun's templating engine to process the template, and the other is to use templates in your own codebase using any templating engine supported by consolidate.js.
|
|||
|
|
|||
|
To use mailgun's templating engine (and allow templates to iterate independent of your codebase), simply pass the template name to the `template` key, and the template variables as a stringified JSON to the `h:X-Mailgun-Variables` key. Here's an example:
|
|||
|

|
|||
|
```javascript
|
|||
|
nodemailerMailgun.sendMail({
|
|||
|
from: 'myemail@example.com',
|
|||
|
to: 'recipient@domain.com', // An array if you have multiple recipients.
|
|||
|
subject: 'Hey you, awesome!',
|
|||
|
template: 'boss_door',
|
|||
|
'h:X-Mailgun-Variables': JSON.stringify({key:'boss'})
|
|||
|
}, (err, info) => {
|
|||
|
if (err) {
|
|||
|
console.log(`Error: ${err}`);
|
|||
|
}
|
|||
|
else {
|
|||
|
console.log(`Response: ${info}`);
|
|||
|
}
|
|||
|
});
|
|||
|
```
|
|||
|
|
|||
|
To use consolidate.js templates locally, give the `template` key an object instead that contains a `name` key, an `engine` key and, optionally, a `context` object. For example, you can use Handlebars templates to generate the HTML for your message like so:
|
|||
|
|
|||
|
```js
|
|||
|
const handlebars = require('handlebars');
|
|||
|
|
|||
|
const contextObject = {
|
|||
|
variable1: 'value1',
|
|||
|
variable2: 'value2'
|
|||
|
};
|
|||
|
|
|||
|
nodemailerMailgun.sendMail({
|
|||
|
from: 'myemail@example.com',
|
|||
|
to: 'recipient@domain.com', // An array if you have multiple recipients.
|
|||
|
subject: 'Hey you, awesome!',
|
|||
|
template: {
|
|||
|
name: 'email.hbs',
|
|||
|
engine: 'handlebars',
|
|||
|
context: contextObject
|
|||
|
}
|
|||
|
}, (err, info) => {
|
|||
|
if (err) {
|
|||
|
console.log(`Error: ${err}`);
|
|||
|
}
|
|||
|
else {
|
|||
|
console.log(`Response: ${info}`);
|
|||
|
}
|
|||
|
});
|
|||
|
```
|
|||
|
|
|||
|
You can use any of the templating engines supported by [Consolidate.js](https://github.com/tj/consolidate.js/). Just require the engine module in your script, and pass a string of the engine name to the `template` object. Please see the Consolidate.js documentation for supported engines.
|
|||
|
|
|||
|
## Mailgun Regions
|
|||
|
|
|||
|
You can use two different region environments for your mailgun domains. For USA region you should use api endpoint ```api.mailgun.net```, but for EU region ```api.eu.mailgun.net```
|
|||
|
|
|||
|
You can pass it as "host" to transport options object:
|
|||
|
|
|||
|
```js
|
|||
|
const nodemailer = require('nodemailer');
|
|||
|
const mg = require('nodemailer-mailgun-transport');
|
|||
|
|
|||
|
const options = {
|
|||
|
auth: {
|
|||
|
api_key: 'key-1234123412341234',
|
|||
|
domain: 'one of your domain names listed at your https://mailgun.com/app/domains'
|
|||
|
},
|
|||
|
host: 'api.eu.mailgun.net' // e.g. for EU region
|
|||
|
}
|
|||
|
|
|||
|
const nodemailerMailgun = nodemailer.createTransport(mg(auth));
|
|||
|
```
|
|||
|
|
|||
|
|
|||
|
**[1]** Quickly install dependencies
|
|||
|
```bash
|
|||
|
npm install nodemailer
|
|||
|
npm install nodemailer-mailgun-transport
|
|||
|
```
|
|||
|
|
|||
|
## Legacy Node.js versions
|
|||
|
|
|||
|
Versions of Node.js before 7.6 are supported via `nodemailer-mailgun-transport/es5`.
|
|||
|
|
|||
|
```js
|
|||
|
const nodemailer = require('nodemailer');
|
|||
|
const mg = require('nodemailer-mailgun-transport/es5');
|
|||
|
|
|||
|
```
|
|||
|
|