Typescript Mailgun wrapper for sending emails in NodeJS
Created and maintained by Stateless Studio
- Create mailgun account (https://www.mailgun.com/)
- Add DNS records
npm i ts-mailgun
import { NodeMailgun } from 'ts-mailgun';
const mailer = new NodeMailgun();
mailer.apiKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // Set your API key
mailer.domain = 'mail.my-sample-app.com'; // Set the domain you registered earlier
mailer.fromEmail = '[email protected]'; // Set your from email
mailer.fromTitle = 'My Sample App'; // Set the name you would like to send from
mailer.init();
// Send an email to [email protected]
mailer
.send('[email protected]', 'Hello!', '<h1>hsdf</h1>')
.then((result) => console.log('Done', result))
.catch((error) => console.error('Error: ', error));or if you're using Express:
// Make sure you init() NodeMailgun before you start your server!
...
router.post('/', (request, response, next) => {
mailer
.send('[email protected]', 'Hello!', '<h1>hsdf</h1>')
.then(() => next())
.catch((error) => response.sendStatus(500));
});
...View the complete NodeMailgun example
You may set additional Mailgun options before initializing by setting NodeMailgun::options:
const mailer = new NodeMailgun();
mailer.apiKey = 'XXXXXXXXXXXXXXXXXXXXXXXXX';
mailer.domain = 'mail.my-sample-app.com';
// Setting Mailgun options
mailer.options = {
host: 'api.eu.mailgun.net'
};
mailer.init();A full list of options may be found here: https://www.npmjs.com/package/mailgun-js#options
You may add additional options to send() by passing an object to sendOptions.
View the Mailgun documentation: https://www.npmjs.com/package/mailgun-js#attachments
const filepath = path.join(__dirname, 'mailgun_logo.png');
mailer.send(
'[email protected]',
'Hello',
'Testing some Mailgun awesomeness!',
{},
{ attachment: filepath } // Set attachment
);Create a mailing list on Mailgun, and copy the alias address it generates.
After you call NodeMailgun::init(), you will need to initialize the list:
Example:
...
mailer.initMailingList('[email protected]')
...mailer.listAdd('[email protected]', 'John Doe', { role: 'Admin' })
.then(() => console.log('Done'))
.catch((error) => console.error(error));mailer.listUpdate('[email protected]', { name: 'Don Boe' })
.then(() => console.log('Done'))
.catch((error) => console.error(error));mailer.listRemove('[email protected]')
.then(() => console.log('Done'))
.catch((error) => console.error(error));Get your mailing list for administration or for bulk sending. You can also filter and map your users before passing the list to send().
getList() gets an array of all users in the list, as objects
mailer.getList()
.then((list) => console.log('List: ', list))
.catch((error) => console.error('Error: ', error));getListAddresses() get an array of email addresses in the list, as strings
mailer.getListAddresses()
.then((list) => console.log('List: ', list))
.catch((error) => console.error('Error: ', error));const newsletter = new NodeMailgun();
newsletter.apiKey = 'xxxxxxxxxxxxxxxxxxxxxxx';
newsletter.domain = 'my-app.com';
newsletter.fromEmail = '[email protected]';
newsletter.fromTitle = 'My App Newsletter';
async function main() {
// Add a member
await newsletter.listAdd('[email protected]', 'Tom Example', {
id: 12,
role: 'Admin'
}).catch((error) => console.error('Error: ', error));
// Get list
const list = await newsletter.getList()
.catch((error) => console.error('Error: ', error));
// Send mail
await mailer
.listSend('[email protected]', 'Newsletter', 'Hello %recipient.name%!')
.catch(console.error);
}
main();We recommend adding an Unsubscribe Link. A default "Unsubscribe" link will be included at the bottom of the email, but you can customize this link if you'd like.
mailer.unsubscribeLink = false;mailer.unsubscribeLink = '<a href="%unsubscribe_url%">Unsubscribe from Cool Emails</a>';To enable test mode, set mailer.testMode to true. Send functions will automatically accept without sending.
You can create templates as a MailgunTemplate, exported from ts-mailgun/mailgun-template. This accepts a subject and body.
Templates use Handlebars as the template language, so you can create templates with variables which will be rendered on send.
Set mailer.templates to a map of templates:
mailer.templates['welcome'] = new MailgunTemplate();
mailer.templates['welcome'].subject = 'Welcome, {{username}}';
mailer.templates['welcome'].body = '<h1>Email: {{email}}</h1>';You can use a template to send your messages. This will render the template for the data you set.
// Send email
let template = mailer.getTemplate('welcome');
if (template && template instanceof MailgunTemplate) {
await mailer
.sendFromTemplate('[email protected]', template, {
username: 'testuser',
email: '[email protected]'
})
.catch((error) => {
console.error(error);
});
}To send via a pre-stored template, leave the body empty and define the template name via:
sendOptions.template = 'TEMPLATENAME'You can load the header & footer from HTML templates:
// Load mailer header/footer
mailer.loadHeaderTemplate('assets/html/email-header.html');
mailer.loadFooterTemplate('assets/html/email-footer.html');If you use an unsubscribe link in your footer template, you will want to disable the default link:
mailer.unsubscribeLink = false;The Mailgun object is exposed through NodeMailgun::mailgun, so you can access it directly
If you'd like to send Generic Requests (https://www.npmjs.com/package/mailgun-js#generic-requests), you may use the mailgun member:
const mailer = new NodeMailgun();
...
mailer.init();
mailer.mailgun.get(
'/samples.mailgun.org/stats',
{ event: ['sent', 'delivered'] },
function (error, body) {
console.log(body);
}
);