Mailgun.js

13.0.0 verified Sat Apr 25 auth: no javascript

Mailgun.js v13.0.0 is a JavaScript SDK for the Mailgun API, supporting Node.js (>=18) and browser environments with CJS, ESM, and AMD bundles. It provides a full client for sending emails, managing mailing lists, domains, suppressions, routes, tags, events, and more. Active development (12 releases in 2 years, monthly cadence). Key differentiators: first-class TypeScript support, explicit FormData passing (universal), subaccount support, and EU API endpoint configuration.

Common errors

error Error: FormData is not a constructor ↓

cause Missing FormData import.

fix

import FormData from 'form-data'; or use built-in FormData in Node >=18.

error Cannot find module 'mailgun.js' ↓

cause Package not installed.

fix

npm install mailgun.js

error TypeError: mg.messages.create is not a function ↓

cause Client not initialized correctly.

fix

Ensure you call mailgun.client() and not use Mailgun directly.

Warnings

breaking In v13.0.0, the `address` property is removed from query parameters for MailingLists.list(). ↓

fix Use MailingListsClient.listByAddress(address) to search by address.

gotcha Browser usage requires a proxy due to CORS; do not expose private API key in frontend. ↓

fix Set up a server-side proxy to forward requests to Mailgun API.

gotcha FormData must be passed to constructor. Starting from v3.0, FormData is required. ↓

fix const mailgun = new Mailgun(FormData); or import FormData from 'form-data';

deprecated The old 'mailgun-js' package is deprecated. Use 'mailgun.js' instead. ↓

fix npm install mailgun.js

Install

npm install mailgun.js

yarn add mailgun.js

pnpm add mailgun.js

Imports

Mailgun

wrong

const { Mailgun } = require('mailgun.js')

correct

import Mailgun from 'mailgun.js'

Default import. In CJS: const Mailgun = require('mailgun.js')

interfaces

wrong

const { IMessagesClient } = require('mailgun.js')

correct

import { IMessagesClient } from 'mailgun.js'

Types are exported but not available in CJS require due to type stripping

Enums

wrong

import Mailgun from 'mailgun.js'; const { MailMan } = Mailgun

correct

import { MailMan } from 'mailgun.js'

Named exports for classes/enums. Available both ESM and CJS

Quickstart

Initializes mailgun client with API key, sends an email, and lists all mailing lists.

import Mailgun from 'mailgun.js';
import FormData from 'form-data';

const mailgun = new Mailgun(FormData);
const mg = mailgun.client({
  username: 'api',
  key: process.env.MAILGUN_API_KEY ?? 'your-api-key',
});

// Send an email
mg.messages.create('sandbox.mailgun.org', {
  from: "Excited User <mailgun@sandbox.mailgun.org>",
  to: ["recipient@example.com"],
  subject: "Hello",
  text: "Testing some Mailgun awesomeness!",
}).then(msg => console.log(msg))
.catch(err => console.error(err));

// List mailing lists
mg.lists.list().then(lists => console.log(lists))
.catch(err => console.error(err));