Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/orliesaurus/nodemailer-mailgun-transport
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://github.com/orliesaurus/nodemailer-mailgun-transport
Last synced: about 2 months ago
JSON representation
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 🔫
- Host: GitHub
- URL: https://github.com/orliesaurus/nodemailer-mailgun-transport
- Owner: orliesaurus
- License: mit
- Created: 2014-08-06T12:09:17.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-09-03T20:17:42.000Z (about 1 year ago)
- Last Synced: 2024-07-24T15:03:13.860Z (2 months ago)
- Language: JavaScript
- Homepage:
- Size: 426 KB
- Stars: 880
- Watchers: 7
- Forks: 98
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
nodemailer-mailgun-transport
============================
[](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 
## 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: '[email protected]',
to: '[email protected]', // An array if you have multiple recipients.
cc:'[email protected]',
bcc:'[email protected]',
subject: 'Hey you, awesome!',
'replyTo': '[email protected]',
//You can use "html:" to send HTML email content. It's magic!
html: 'Wow Big powerful letters',
//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
![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
"``` format. "name" is optional, "address" is required. Missing or null address in object is skipped.
Examples:
```js
from: {name: 'Sales', address: '[email protected]'},
to: [{name:'Mary', address:'[email protected]'}, {address:'[email protected]'}]
```
is converted to:
```js
from: 'Sales ',
to: 'Mary ,[email protected]'
```
## 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: '[email protected]',
to: '[email protected]', // 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: '[email protected]',
to: '[email protected]', // 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');
```