Mailgun.js

A javascript sdk for Mailgun built with webpack, babel & es6. This can be used in node or in the browser*.

NOTE: If used in the browser, a proxy is required to communicate with the Mailgun api due to cors limitations. Also, do not publish your private api key in frontend code.

__Table of Contents__

- Documentation
- Install
- Setup Client
- Available Imports
- Types imports
- Interfaces and Enums imports
- Fetch API usage
- Proxy configuration
- SubAccounts
- Generated docs
- Methods
- Pagination
- Browser Demo
- Examples
- Development
- Requirements
- Build
- Tests
- Release Process

Documentation

Mailgun API Documentation

Install

- Requires node.js >= 18.x

Install mailgun.js with:

``SH npm install mailgun.js`

`Setup Client`

The next step is to import the module and instantiate a mailgun client by calling new Mailgun(formData) and then using mailgun.client setup the client with basic auth credentials (username: 'api', key: 'MAILGUN_API_KEY').

NOTE: starting from version 3.0 you need to pass FormData (we need this to keep library universal). For node.js you can use built-in FormData or form-data library.

IMPORTANT: if you use EU infrastructure, you need to also pass url: 'https://api.eu.mailgun.net' together with auth credentials as stated in Mailgun docs

`$3`


Once the package is installed, you can import the library using

import or require approach:

`js const Mailgun = require('mailgun.js'); const mailgun = new Mailgun(FormData); // or const formData = require('form-data'); const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'MAILGUN_API_KEY'});``js import Mailgun from 'mailgun.js'; const mailgun = new Mailgun(FormData); // or import formData from 'form-data'; const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'MAILGUN_API_KEY'});`

Be aware that there are four bundles available for usage. All of them are conditionally exported by package.json and separated by environment (Browser/Node.js): - Node.js environment: - CommonJS (CJS), a bundle to use with the CommonJS module system in Node.js.

Usage example:

`JS // In this case, the .dist/CJS/mailgun.node.cjs file is expected to be used const Mailgun = require('mailgun.js'); const mailgun = new Mailgun(FormData);`

- ECMAScript modules (ESM) a bundle for the Node.js environment

Usage example:`JS // In this case, the .dist/ESM/mailgun.node.js file is expected to be used import Mailgun from 'mailgun.js'; const mailgun = new Mailgun(FormData); ...`or with dynamic imports:`JS // In this case, the .dist/ESM/mailgun.node.js file is expected to be used const Mailgun = await import('mailgun.js'); const mailgun = new Mailgun.default(FormData); ...`

- Browser environment: - Asynchronous Module Definition (AMD), a bundle to use with theRequire.js module loader in the browser. This bundle requires the RequireJS module loader to be present in the environment.

Usage example for the case when the distribution is used directly in the browser:`HTML`

- ECMAScript modules (ESM) a bundle for browser environment.

Usage example for the case the distribution is used directly in the browser:`HTML`or with dynamic imports:`HTML`

`$3`


Types defined by SDK can be imported from 'definitions' submodule:

TS
 import { MailgunClientOptions, MessagesSendResult } from 'mailgun.js/definitions';


$3

Interfaces and Enums defined by SDK can be imported from 'definitions' submodule:

TS
  import { Interfaces, Enums } from 'mailgun.js/definitions';
  ...
  const mailgunClient: Interfaces.IMailgunClient = mailgun.client(clientOptions);
  const yes = Enums.YesNo.YES;
  ...

$3

Starting from version 12.1.0, the Fetch API is available for use in environments that do not support XMLHttpRequest.

The new useFetch configuration parameter is responsible for this.

Note that proxy configuration and the form-data NPM package are not supported in this case.

Example:

`TS import Mailgun from 'mailgun.js'; const mailgun = new Mailgun(FormData);

const mg = mailgun.client({ username: 'api', key: process.env.MAILGUN_API_KEY || 'MAILGUN_API_KEY', useFetch: true, });`

`$3`


By leveraging client configuration options, users can effortlessly establish proxy connections that align with their network requirements.
Example:

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

const mg = mailgun.client({ username: 'api', key: process.env.MAILGUN_API_KEY || 'MAILGUN_API_KEY', proxy: { protocol: 'https' // 'http' , host: '127.0.0.1', // use your proxy host here port: 9000, // use your proxy port here auth: { // may be omitted if proxy doesn't require authentication username: 'user_name', // provide username password: 'user_password' // provide password } }, });`

`$3`


Primary accounts can make API calls on behalf of their subaccounts. API documentation

js
  import Mailgun from 'mailgun.js';
  const mailgun = new Mailgun(FormData); // or import FormData from 'form-data'
  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'MAILGUN_API_KEY'});
  mg.setSubaccount('subaccount-id');
  // then, if you need to reset it back to the primary account:
  mg.resetSubaccount();



$3

The list of all available Types, Interfaces and Enums is auto-generated and located in the docs folder.
Methods

The following service methods are available to instantiated clients. The examples assume you have already created a mailgun client as mg with valid credentials.

- Documentation - Install - Setup Client - Methods - messages - create - retrieveStoredEmail - resendEmail - getMessagesQueueStatus - clearMessagesQueue - domains - list - get - create - update - verify - destroy - getTracking - updateTracking - getConnection - updateConnection - updateDKIMAuthority - updateDKIMSelector - getIps - assignIp - domain templates - list - get - create - update - destroy - destroyAll - listVersions - getVersion - createVersion - updateVersion - destroyVersion - domain tracking - getTracking - updateTracking - get - generate - regenerate - domain keys - list - listAll - create - activate - deactivate - destroy - updateDKIMAuthority - updateDKIMSelector - events - get - Example with Date and Filter field - logs - list - stats - Stats Options - getDomain - getAccount - metrics - getAccount - getAccountUsage - suppressions - list - Bounces Example - Unsubscribes Example - Complaints Example - get - Bounces Example - Unsubscribes Example - Complaints Example - create - Bounces Example - Unsubscribes Example - Unsubscribe from one tag - Unsubscribe from particular tags - Complaints Example - destroy - Bounces Example - Unsubscribes Example - Complaints Example - upload - Bounces list upload example - Unsubscribes list upload example - Complaints list upload example - Whitelists list upload example - webhooks - list - get - create - update - destroy - routes - list - get - create - update - destroy - validate - get - multiple validation - create - list - get - destroy - mailing lists - list - get - create - update - destroy - mailing list members - listMembers - getMember - createMember - createMembers - updateMember - destroyMember - subaccounts - list - get - create - enable - disable - destroy - setMonthlySendingLimit - getMonthlySendingLimit - updateSubaccountFeature - inbox placements - SeedsLists - list - get - create - update - destroy - SeedsLists Attributes - list - get - SeedsLists Filters - list - Providers - list - Results - list - get - destroy - getResultByShareId - Results Attributes - list - get - Results Filters - list - Sharing - get - update - Run Test - DKIM Management - update - Bounce Classification - list - Tags - list - limits - update - destroy - Navigation thru lists - Browser Demo - Development - Requirements - Build - Tests - Release Process - TODO

`$3`

get or get{{Item}}

 - expected response for client is a single object
-

list or list{{Items}}

 - expected response for client is a list of objects
-

create or create{{Item}}

 - expected response for client is a single object
-

update or update{{Item}}

 - expected response is an object with a status message
-

destroy or destroy{{Item}}

 - expected response is an object with a status message
$3
- #### create
   API Reference

mg.messages.create(domain, data)

Options:

Parameter | Description :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- to | Email address of the recipient(s). Example: "Bob ". You can use commas to separate multiple recipients (e.g.: "test@example.com,test@example.com" or ["test@example.com", "test@example.com"]). cc | Same asTo but for carbon copybcc | Same asTo but for blind carbon copysubject | Subject of the message. html | HTML version of the message. text | Text version of the message. message | MIME string of the message. Make sure to use multipart/form-data to send this as a file upload. attachment | File attachment. You can post multiple attachment values. Important: You must use multipart/form-data encoding when sending attachments. Also you can use{data: file, filename: filename}to define custom filename. o:tag | Tag string. See Tagging for more information. o:campaign | Id of the campaign the message belongs to. See um-campaign-analytics for details. o:deliverytime | Desired time of delivery. See Date Format. Note: Messages can be scheduled for a maximum of 3 days in the future. o:dkim | Enables/disabled DKIM signatures on per-message basis. Pass yes or no o:testmode | Enables sending in test mode. Pass yes if needed. See Sending in Test Mode o:tracking | Toggles tracking on a per-message basis, see Tracking Messages for details. Pass yes or no. o:tracking-clicks | Toggles clicks tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes, no or htmlonly. o:tracking-opens | Toggles opens tracking on a per-message basis. Has higher priority than domain-level setting. Pass yes or no. h:X-My-Header | h: prefix followed by an arbitrary value allows to append a custom MIME header to the message (X-My-Header in this case). For example, h:Reply-To to specify Reply-To address. v:my-var | v: prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See Attaching Data to Messages for more information.

- HTML/TEXT Example:

`JS mg.messages.create('sandbox-123.mailgun.org', { from: "Excited User ", to: ["test@example.com"], subject: "Hello", text: "Testing some Mailgun awesomness!", html: "

`Testing some Mailgun awesomness!`

"
      })
      .then(msg => console.log(msg)) // logs response data
      .catch(err => console.error(err)); // logs any error


  - MIME Example:

`js mg.messages.create('sandbox-123.mailgun.org', { from: "Excited User ", to: ["test@example.com"], subject: "Hello", message: "" }) .then(msg => console.log(msg)) // logs response data .catch(err => console.error(err)); // logs any error`

- Messages with attachments:

- Node.js example of send file as an attachment

`js const fsPromises = require('fs').promises; const path = require('path'); const filepath = path.resolve(__dirname, '../test.pdf'); let messageParams = { from: "Excited User ", to: ["test@example.com"], subject: "Test subject", text: "Hello here is a file in the attachment" }

fsPromises.readFile(filepath) .then(data => { const file = { filename: 'test-rename.pdf', data } messageParams.attachment = file; return mg.messages.create('sandbox-123.mailgun.org', messageParams); }) .then(response => { console.log(response); })`- Node.js example of send multiple files as an attachment`js const fsPromises = require('fs').promises; const path = require('path'); const filepath = path.resolve(__dirname, '../test.pdf'); const filepath1 = path.resolve(__dirname, '../test.jpg');

let messageParams = { from: "Excited User ", to: ["test@example.com"], subject: "Test subject", text: "Test message" }

(async () =>{ try { const firstFile = { filename: 'test.pdf', data: await fsPromises.readFile(filepath) }

const secondFile = { filename: 'test.jpg', data: await fsPromises.readFile(filepath1) }

messageParams.attachment = [firstFile, secondFile]; const result = await mg.messages.create('sandbox-123.mailgun.org', messageParams); console.log(result); } catch (error) { console.error(error); } })()`- Node.js example of send file as inline image`js const fsPromises = require('fs').promises; const path = require('path'); const filepath = path.resolve(__dirname, '../test.jpg'); let messageParams = { from: "Excited User ", to: ["test@example.com"], subject: "Test subject", html: '

 Some extra text'
        }
        fsPromises.readFile(filepath)
        .then(data => {
          const file = {
              filename: 'test.jpg',
              data
          }

messageParams.inline = file; return mg.messages.create('sandbox-123.mailgun.org', messageParams); }) .then(response => console.log(response))`- Browser example of send file

Before sending the file you need to somehow get the Blob of the file. Usually can get it from the onChange event of input tag with type file.`js const handleFileSelected = async (event) => { const files = Array.from(event.target.files) const fileBuffer = await files[0]; }`

Then you can use the same approach as shown above for node.js apps.`js const file = { filename: 'test.pdf', data: fileBuffer };

let messageParams = { from: "Excited User ", to: ["test@example.com"], subject: "Test subject", text: "Hello here is a file in the attachment", attachment: file };

const res = await mg.messages.create(DOMAIN, messageParams);`Promise returns:

`js { id: '<20151025002517.117282.79817@sandbox-123.mailgun.org>', message: 'Queued. Thank you.' }`

- #### retrieveStoredEmail API Reference

mg.messages.retrieveStoredEmail(domain, storageKey)

storageKey - Storage key from the email's associated events (Example: Accepted/Delivered events storage.key field). Mentioned events can be found on https://app.mailgun.com/ (Send -> logs).

Note: Storage keys are available for the duration of your domain's message retention policy.

Example:

`JS mg.messages.retrieveStoredEmail('sandbox-123.mailgun.org', 'BABEAAeEDgPUyeFqr-tATLaCfYqyqvLpbg') .then(storedEmail => console.log(storedEmail)) // logs response data .catch(err => console.error(err)); // logs any error`

Promise returns:

`JS { 'Content-Type': 'multipart/alternative; boundary="boundary_12345"', From: 'postmaster@sandbox.mailgun.org', 'Message-Id': '<123.123@sandbox.mailgun.org>', 'Mime-Version': '1.0', Subject: 'Hello', To: 'foo@example.com', 'X-Mailgun-Deliver-By': 'Fri, 28 Nov 2025 18:02:00 +0000', sender: 'postmaster@sandbox.mailgun.org', recipients: 'foo@example.com', from: 'postmaster@sandbox.mailgun.org', subject: 'Hello', 'body-html': 'Test', 'body-plain': 'Testing some Mailgun awesomness!', attachments: [], 'content-id-map': {}, 'message-headers': [ ['Mime-Version', '1.0'], [ 'Content-Type', 'multipart/alternative; boundary="boundary_12345' ], ['Subject', 'Hello'], ['From', 'postmaster@sandbox.mailgun.org'], ['To', 'foo@example.com'], ['X-Mailgun-Deliver-By', 'Fri, 28 Nov 2025 18:02:00 +0000'], [ 'Message-Id', '<123.123@sandbox.mailgun.org>' ] ], 'stripped-html': 'Test', 'stripped-text': 'Testing some Mailgun awesomness!', 'stripped-signature': '' }`

- ### resendEmail API Reference

mg.messages.resendEmail(domain, storageKey, recipient)

storageKey - Storage key from the email's associated events (Example: Accepted/Delivered events storage.key field). Mentioned events can be found on https://app.mailgun.com/ (Send -> logs).

Note: Storage keys are available for the duration of your domain's message retention policy.

recipient - Email address of the recipient(s). Supports friendly name format. Example: "Bob ". Use commas to separate multiple recipients. Duplicate addresses are automatically ignored.

Example:

`JS mg.messages.resendEmail( 'sandbox-123.mailgun.org', 'BABEAAeEDgPUyeFqr-tATLaCfYqyqvLpbg', 'foo@test.com, bar@test.com' ).then(resendStatus => console.log(resendStatus)) // logs response data .catch(err => console.error(err)); // logs any error`

Promise returns:

`JS { id: '<20151025002517.117282.79817@sandbox-123.mailgun.org>', message: 'Queued. Thank you.' }`

- ### getMessagesQueueStatus API Reference

mg.messages.getMessagesQueueStatus(domain)

Example:

`JS mg.messages.getMessagesQueueStatus('sandbox-123.mailgun.org') .then(queueStatus => console.log(queueStatus)) // logs response data .catch(err => console.error(err)); // logs any error`

Promise returns:

`JS { regular: { is_disabled: false, disabled: { until: null, reason: '' } }, scheduled: { is_disabled: true, disabled: { until: new Date('2025-11-28T18:02:00Z'), reason: 'High load' } } }`

- ### clearMessagesQueue Deletes all scheduled and undelivered mail from the domain queue.