simple-mailgun.js

A simple, tiny Mailgun client for Node.js. (Currently only supports sending emails, will add more features as needed)

• 🐤 Tiny wrapper around the Mailgun API
• ⚙️ Auto-config from environment variables
• 💬 Optional debug logging
• 🔁 Retry on HTTP 429 with truncated exponential backoff
• ✅ 100% test coverage

Installation

npm i simple-mailgun.js

Usage

Creating the client

You can get an API key by following the official docs.

const { createMailgunClient } = require('simple-mailgun.js');

const client = createMailgunClient({
  domain: "mail.example.com",
  apiKey: "FAKE_API_KEY",
		
  debugLogging: true // Optional, default to false
});

Note: You can also set the MAILGUN_DOMAIN and MAILGUN_API_KEY environment variables, and they'll be picked up automatically.

process.env.MAILGUN_DOMAIN = "mail.example.com";
process.env.MAILGUN_API_KEY = "API KEY";

const client = createMailgunClient(); // No args necessary

Sending emails

const response = await client.sendMessage({
	from: "[email protected]",
	to: "[email protected]",
	subject: "Testing",
	text: "Hello from SimpleMailgun.js"
});
// # => { "id": "<[email protected]>", "message": "Queued. Thank you." }

You can put whatever params you want into the options object. The params will be serialized into a FormData and sent to Mailgun's API. The full of options you can send is here.

Development

Run tests:

npm run test

Runs Jest in watch mode

Publish new version to NPM:

npm run publish

Why another Mailgun client?

Mailgun has two existing Node.js SDKs (official SDK, legacy SDK).

Both are too bloody complicated and give me inscrutable errors. I just want to send emails.

This library does what I need in 87 lines, and now I can get on with my life.

</rant>

Thank You

Development sponsored by razorUX