mailgun.js

v14.0.1

Published

a month ago

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

Downloads

4,604,910

0High
0Medium
0Low

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

Mailgun API Documentation

Install

Requires node.js >= 18.x

Install mailgun.js with:

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

Imports

Once the package is installed, you can import the library using import or require approach:

  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'});

  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:

// 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:

// 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:

// 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 the Require.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:
```
<script src='http://requirejs.org/docs/release/2.3.6/comments/require.js'></script>
<script>
require(['./dist/AMD/mailgun.amd.js'], function(Mailgun) {
  const mailgun = new Mailgun(FormData);
  ...
})
</script>
```

ECMAScript modules (ESM) a bundle for browser environment.

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

<script type="module">
  import Mailgun from './dist/ESM/mailgun.browser.js';
  const mailgun = new Mailgun(FormData);
  ...
</script>

or with dynamic imports:

<script>
import ('./dist/ESM/mailgun.browser.js').then(Mailgun =>{
  const mailgun = new Mailgun.default(FormData);
  ...
})
</script>

Types imports

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

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

Interfaces and Enums imports

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

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

Fetch API usage

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:

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,
});

Proxy configuration

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

  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
      }
    },
  });

SubAccounts Usage

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

  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();

Generated docs

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.

Method naming conventions:

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Mailgun.js

Documentation

Install

Setup Client

Imports

Types imports

Interfaces and Enums imports

Fetch API usage

Proxy configuration

SubAccounts Usage

Generated docs

Methods

Method naming conventions:

Messages

create

retrieveStoredEmail

resendEmail

getMessagesQueueStatus

clearMessagesQueue

Templates

Recipient Variables

Domains

list

get

create

verify

update

destroy

getTracking

updateTracking

getConnection

updateConnection

updateDKIMAuthority

updateDKIMSelector

getIps

assignIp

deleteIp

Domain credentials

list

create

update

destroy

destroyAll

Domain templates

list

get

create

update

destroy

destroyAll

listVersions

getVersion

createVersion