mailgun.js

- [Available Imports](#imports)
- [Using Subaccounts](#using-subaccounts)
- [Types imports](#types-imports)
- [Interfaces and Enums imports](#interfaces-and-enums-imports)

• Development

Install

• Requires node.js >= 18.x

npm install mailgun.js

Setup Client

Imports

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

import * as FormData from 'form-data';
import Mailgun from 'mailgun.js';
const mailgun = new Mailgun(FormData);
const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});

Using Subaccounts

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

Proxy configuration

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

const mg = mailgun.client({
  username: 'api',
  key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere',
  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
    }
  },
});

Types imports

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

Interfaces and Enums imports

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

Generated docs

Methods

• Documentation

- [messages](#messages)
  - [create](#create)
- [domains](#domains)
  - [list](#list)
  - [get](#get)
  - [create](#create-1)
  - [update](#update)
  - [destroy](#destroy)
  - [getTracking](#gettracking)
  - [updateTracking](#updatetracking)
  - [getIps](#getips)
  - [assignIp](#assignip)
- [events](#events)
  - [get](#get-1)
    - [Example with Date and *Filter field*](#example-with-date-and-filter-field)
- [stats](#stats)
  - [getDomain](#getdomain)
  - [getAccount](#getaccount)
- [suppressions](#suppressions)
  - [list](#list-1)
    - [Bounces Example](#bounces-example)
    - [Unsubscribes Example](#unsubscribes-example)
    - [Complaints Example](#complaints-example)
  - [get](#get-2)
    - [Bounces Example](#bounces-example-1)
    - [Unsubscribes Example](#unsubscribes-example-1)
    - [Complaints Example](#complaints-example-1)
  - [create](#create-2)
    - [Bounces Example](#bounces-example-2)
    - [Unsubscribes Example](#unsubscribes-example-2)
      - [Unsubscribe from one tag](#unsubscribe-from-one-tag)
      - [Unsubscribe from particular tags](#unsubscribe-from-particular-tags)
    - [Complaints Example](#complaints-example-2)
  - [destroy](#destroy-1)
    - [Bounces Example](#bounces-example-3)
    - [Unsubscribes Example](#unsubscribes-example-3)
    - [Complaints Example](#complaints-example-3)
- [webhooks](#webhooks)
  - [list](#list-2)
  - [get](#get-3)
  - [create](#create-3)
  - [update](#update-1)
  - [destroy](#destroy-2)
- [routes](#routes)
  - [list](#list-3)
  - [get](#get-4)
  - [create](#create-4)
  - [update](#update-2)
  - [destroy](#destroy-3)
- [validate](#validate)
  - [get](#get-5)
- [multiple validation](#multiple-validation)
  - [create](#create-5)
  - [list](#list-4)
  - [get](#get-5)
  - [destroy](#destroy-4)
- [mailing lists](#mailing-lists)
  - [list](#list-5)
  - [get](#get-6)
  - [create](#create-6)
  - [update](#update-3)
  - [destroy](#destroy-5)
- [mailing list members](#mailing-list-members)
  - [listMembers](#listmember)
  - [getMember](#getmember)
  - [createMember](#createmember)
  - [createMembers](#createmembers)
  - [updateMember](#updatemember)
  - [destroyMember](#destroymember)
- [subaccounts](#subaccounts)
  - [list](#list-6)
  - [get](#get-8)
  - [create](#create-7)
  - [enable](#enable)
  - [disable](#disable)

• Development

• 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

Messages

• create

```JS
mg.messages.create('sandbox-123.mailgun.org', {
    from: "Excited User <mailgun@sandbox-123.mailgun.org>",
    to: ["test@example.com"],
    subject: "Hello",
    text: "Testing some Mailgun awesomness!",
    html: "<h1>Testing some Mailgun awesomness!</h1>"
  })
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

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

- 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 <mailgun@sandbox-123.mailgun.org>",
        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 <mailgun@sandbox-123.mailgun.org>",
      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 <mailgun@sandbox-123.mailgun.org>",
        to: ["test@example.com"],
        subject: "Test subject",
        html: '<div><img alt="image" id="1" src="cid:test.jpg"/></div> 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];
  }
  <input type="file" onChange={handleFileSelected} name="file-uploader"/>
  ```

  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 <mailgun@sandbox-123.mailgun.org>",
      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);
  ```

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

Templates

"title": "A title",
"body": "The body"

• Providing values for title and slug variables to render in template

...
const {
  title,
  slug,
} = someDataSource;

const mailgunData = {
  from: 'mailer@example.com>',
  to: 'recipient@example.com',
  subject: `Email ${title}`,
  template: 'name-of-the-template-you-made-in-mailgun-web-portal',
  'h:X-Mailgun-Variables': JSON.stringify({ // be sure to stringify your payload
    title,
    slug,
  }),
  'h:Reply-To': 'reply-to@example.com',
};

try {
  const response = await mailgun.messages.create(DOMAIN_NAME, mailgunData);
...

• Providing an array of objects to render them in the template

...
const mailgunData = {
  from: 'mailer@example.com>',
  to: 'recipient@example.com',
  subject: `Email ${title}`,
  template: 'name-of-the-another-template-you-made-in-mailgun-web-portal',
  'h:X-Mailgun-Variables': JSON.stringify({
  "arrayItems": [
      {
          "question": "test_question",
          "answer": "test_answer"
      },
      {
          "question": "test_question",
          "answer": "test_answer"
      }
  ]})
};
try {
  const response = await mailgun.messages.create(DOMAIN_NAME, mailgunData);
...

Recipient Variables

from: 'Example.com Mailer <mailer@mailer.example.com>',
to: ['me@example.com', 'you@example.com'],
subject: 'Recipient - %recipient.title%',
html: 'Here\'s %recipient.title% and <a href="%recipient.link%">link</a>',
'recipient-variables': JSON.stringify({
  'me@example.com': {
    title: 'Me',
    link: 'href-var',
  },
  'you@example.com': {
    title: 'You',
    link: 'slug-recipient-var-c',
  },
}),
    };

    try {
const response = await mailgun.messages.create(DOMAIN_NAME, mailgunData);

Domains

• list

.then(domains => console.log(domains)) // logs array of domains
.catch(err => console.error(err)); // logs any error

created_at: 'Sun, 19 Oct 2014 18:49:36 GMT',
name: 'testing.example.com',
receiving_dns_records: null,
require_tls: true,
sending_dns_records: null,
skip_verification: true,
smtp_login: 'postmaster@testing.example.com',
smtp_password: 'password',
spam_action: 'disabled',
state: 'unverified',
type: 'custom',
wildcard: true

• get

.then(domains => console.log(domains)) // logs domain object
.catch(err => console.error(err)); // logs any error

created_at: 'Sun, 19 Oct 2014 18:49:36 GMT',
name: 'testing.example.com',
receiving_dns_records: [{
    "name": "testing.example.com",
    "record_type": "TXT",
    "valid": "unknown",
    "value": "v=spf1 include:mailgun.org ~all"
  },
  {
    "name": "k1._domainkey.testing.example.com",
    "record_type": "TXT",
    "valid": "unknown",
    "value": "k=rsa; 123456"
  },
  {
    "name": "email.testing.example.com",
    "record_type": "CNAME",
    "valid": "unknown",
    "value": "mailgun.org"
  }],
require_tls: true,
sending_dns_records: [{
    "priority": "10",
    "record_type": "MX",
    "valid": "unknown",
    "value": "mxa.mailgun.org"
  },
  {
    "priority": "10",
    "record_type": "MX",
    "valid": "unknown",
    "value": "mxb.mailgun.org"
  }],
skip_verification: true,
smtp_login: 'postmaster@testing.example.com',
smtp_password: 'password',
spam_action: 'disabled',
state: 'unverified',
type: 'custom',
wildcard: true,
id: '64a4291ebbe4ec7e1d78bc80',
is_disabled: false,
web_prefix: 'email',
web_scheme: 'http'

• create

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

"name": "foobar.example.com",
"record_type": "TXT",
"valid": "unknown",
"value": "v=spf1 include:mailgun.org ~all"
    },
    {
"name": "k1._domainkey.foobar.example.com",
"record_type": "TXT",
"valid": "unknown",
"value": "k=rsa; 123456"
    },
    {
"name": "email.foobar.example.com",
"record_type": "CNAME",
"valid": "unknown",
"value": "mailgun.org"
    }

"priority": "10",
"record_type": "MX",
"valid": "unknown",
"value": "mxa.mailgun.org"
    },
    {
"priority": "10",
"record_type": "MX",
"valid": "unknown",
"value": "mxb.mailgun.org"

wildcard: 'true',
web_scheme: 'http',
spam_action: 'disabled',
    })
    .then(msg => console.log(msg)) // logs response data
    .catch(err => console.error(err)); // logs any error

name: 'foobar.example.com',
require_tls: false,
skip_verification: false,
state: 'unverified',
wildcard: true,
spam_action: 'disabled',
created_at: 'Tue, 04 Jul 2023 14:09:18 GMT',
smtp_password: undefined,
smtp_login: 'postmaster@foobar.example.com',
type: 'custom',
receiving_dns_records: [
  {
    is_active: true,
    cached: [],
    priority: '10',
    record_type: 'MX',
    valid: 'unknown',
    value: 'mxa.mailgun.org'
  },
  {
    is_active: true,
    cached: [],
    priority: '10',
    record_type: 'MX',
    valid: 'unknown',
    value: 'mxb.mailgun.org'
  }
],
sending_dns_records: [
  {
    is_active: true,
    cached: [],
    name: 'foobar.example.com',
    record_type: 'TXT',
    valid: 'unknown',
    value: 'v=spf1 include:mailgun.org ~all'
  },
  {
    is_active: true,
    cached: [],
    name: 'email.foobar.example.com',
    record_type: 'CNAME',
    valid: 'unknown',
    value: 'mailgun.org'
  }
],
id: '64a5880eere4eg7e1d85bc69',
is_disabled: false,
web_prefix: 'email',
web_scheme: 'http'

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

message: "Domain has been deleted"

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

"click": {
  "active": false
},
"open": {
  "active": false
},
"unsubscribe": {
  "active": false,
  "html_footer": "\n<br>\n<p><a href=\"%unsubscribe_url%\">unsubscribe</a></p>\n",
  "text_footer": "\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n"
}

```js
mg.domains.updateTracking('foobar.example.com', 'open', {active: true})
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

Open tracking data object properties:

| Property | Description                                |
|:----------|:-------------------------------------------|
| active    | Boolean, enables or disables open tracking |

Promise returns:

```JS
{
  message: 'Tracking settings have been updated',
  open: {
    active: true
  }
}
```

```JS
mg.domains.updateTracking('foobar.example.com', 'click', {active: true})
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

Click tracking data object properties:

| Property | Description                                 |
|:----------|:--------------------------------------------|
| active    | Boolean, enables or disables click tracking |

Promise returns:

```JS
{
  message: 'Tracking settings have been updated',
  click: {
    active: true
  }
}
```

```js
mg.domains.updateTracking('foobar.example.com', 'unsubscribe', {
    active: true,
    html_footer: "\n<br>\n<p><a href=\"%unsubscribe_url%\">unsubscribe</a></p>\n",
    text_footer: "\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n"
  })
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

Unsubscribe Tracking data object properties:

| Property   | Description                                                   |
|:------------|:--------------------------------------------------------------|
| active      | Boolean, enables or disables unsubscribe tracking             |
| html_footer | string appended to html emails for managing unsubscribe links |
| text_footer | string appended to html emails for managing unsubscribe links |

Promise returns:

```JS
{
  message: 'Tracking settings have been updated',
  "unsubscribe": {
    "active": true,
    "html_footer": "\n<br>\n<p><a href=\"%unsubscribe_url%\">unsubscribe</a></p>\n",
    "text_footer": "\n\nTo unsubscribe click: <%unsubscribe_url%>\n\n"
  }
}
```

`mg.domains.getIps(domain)`

Example:

```js
mg.domains.getIps('foobar.example.com')
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

Promise returns:

```JS
["192.168.0.1", "192.168.0.2"]
```

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

message: 'success',
status: 200,

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

message: 'success'

page: 'mypageid',
event: 'opened'

.catch(err => console.error(err)); // logs any error

```js
  const date = new Date(2023, 7, 2, 0, 0, 0, 0); // Wed Aug 02 2023 00:00:00 GMT+0300
    const events = await mg.events.get('foobar.example.com', {
      begin: date.toUTCString(), // 'Tue, 01 Aug 2023 21:00:00 GMT'
      ascending: 'yes',
      limit: 5,
      event: 'delivered'
    });
```

type: 'accepted',
summary: 'got it',
content: { more: 'data' },
timestamp: Wed Nov 19 2014 10:32:57 GMT-0800 (PST) },
    }],
    pages: {
first: { id: 'first', number: 'W3siYSI6IGZhbHNlLC', url: 'apiurl' },
last: { id: 'last', number: 'W3siYSI6IGZhbHNlLC', url: 'apiurl' },
next: { id: 'next', number: W3siYSI6IGZhbHNlLC'', url: 'apiurl' },
previous: { id: 'previous', number: 'W3siYSI6IGZhbHNlLC', url: 'apiurl' }
    }

| Parameter  | Description                                                                                                                |
|:-----------|:---------------------------------------------------------------------------------------------------------------------------|
| event      | The type of the event. For a complete list of all events written to the log see the `Event Types` table below. (Required)  |
| start      | The starting time. Should be in :rfc:`2822#page-14` or unix epoch format. Default: 7 days from the current time.           |
| end        | The ending date. Should be in :rfc:`2822#page-14` or unix epoch format. Default: current time.                             |
| resolution | Can be either ``hour``, ``day`` or ``month``. Default: ``day``                                                             |
| duration   | Period of time with resolution encoded. If provided, overwrites the start date. See list below.                                             |

Duration is a string that represents a period of time with some resolution. It has a format `[0-9]+[m,d,h]` where

- `h` - an hour
- `d` - a day
- `m` - a month

Examples:

- `24h` - a period of 24 hours (a day) with hourly resolution
- `1d` - a period of 1 day with daily resolution
- `2m` - a period of 2 months with monthly resolution

Event Types

| Event Type   | Description                                                                                                                                                                       |
|:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| accepted     | Mailgun accepted the request to send/forward the email and the message has been placed in queue.                                                                                  |
| delivered    | Mailgun sent the email and it was accepted by the recipient email server.                                                                                                         |
| failed       | Mailgun could not deliver the email to the recipient email server.                                                                                                                |
| opened       | The email recipient opened the email and enabled image viewing. Open tracking must be enabled in the Mailgun control panel, and the CNAME record must be pointing to mailgun.org. |
| clicked      | The email recipient clicked on a link in the email. Click tracking must be enabled in the Mailgun control panel, and the CNAME record must be pointing to mailgun.org.            |
| unsubscribed | The email recipient clicked on the unsubscribe link. Unsubscribe tracking must be enabled in the Mailgun control panel.                                                           |
| complained   | The email recipient clicked on the spam complaint button within their email client. Feedback loops enable the notification to be received by Mailgun.                             |
| stored       | Mailgun has stored an incoming message

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

start: Sun Mar 15 2015 17:00:00 GMT-0700 (PDT),
end: Sun Mar 22 2015 17:00:00 GMT-0700 (PDT),
resolution: 'day',
stats: [{
  time: Sun Mar 15 2015 17:00:00 GMT-0700 (PDT),
  delivered: { smtp: 2, http: 1, total: 3 }
}]

• getAccount

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

start: Sun Mar 15 2015 17:00:00 GMT-0700 (PDT),
end: Sun Mar 22 2015 17:00:00 GMT-0700 (PDT),
resolution: 'day',
stats: [{
  time: Sun Mar 15 2015 17:00:00 GMT-0700 (PDT),
  delivered: { smtp: 2, http: 1, total: 3 }
}]

Suppressions

• list

```js
mg.suppressions.list('foobar.example.com', 'bounces')
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

```js
mg.suppressions.list('foobar.example.com', 'unsubscribes')
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

```js
mg.suppressions.list('foobar.example.com', 'complaints')
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

Promise returns:

```JS
{
items: [
  {
    type: "bounces",
    address: "unknown@unknown.com",
    code: 550,
    error: "No such mailbox",
    created_at: Fri Oct 21 2011 04:02:55 GMT-0700 (PDT)
  }],
pages: {
  first: { id: "first", page: "", address: "", url: "apiurl" },
  last: { id: "last", page: "", address: "", url: "apiurl" },
  next: { id: "next", page: "", address: "", url: "apiurl" },
  previous: { id: "prev", page: "", address: "", url: "apiurl" }
}
}
```

• get

```js
mg.suppressions.get('foobar.example.com', 'bounces', 'address@example.com')
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

```js
mg.suppressions.get('foobar.example.com', 'unsubscribes', 'address@example.com')
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

```js
mg.suppressions.get('foobar.example.com', 'complaints', 'address@example.com')
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.error(err)); // logs any error
```

type: "bounces",
address: "address?@unknown.com",
tags: [ "*" ],
created_at: Fri Oct 21 2011 05:02:55 GMT-0700 (PDT)

• create

`mg.suppressions.create(domain, suppressionType, data || data[])`

- #### Bounces Example:
  ```JS
  mg.suppressions.create('foobar.example.com', 'bounces', [{address: 'bob@example.com'}])
    .then(msg => console.log(msg)) // logs response data
    .catch(err => console.error(err)); // logs any error
  ```

  Bounces Options: Contains an array with the following object properties

  | Parameter  | Description                                                                     |
  |:-----------|:--------------------------------------------------------------------------------|
  | address    | Valid email address                                                             |
  | code       | Error code (optional, default: 550)                                             |
  | error      | Error description (optional, default: empty string)                             |
  | created_at | Timestamp of a bounce event in RFC2822 format (optional, default: current time) |

  Promise returns:

  ```js
  {
    message: "1 address has been added to the bounces table"
  }
  ```

- #### Unsubscribes Example:

  ```js
  mg.suppressions.create('foobar.example.com', 'unsubscribes', {address: 'bob@example.com'})
    .then(msg => console.log(msg)) // logs response data
    .catch(err => console.error(err)); // logs any error
  ```

  Unsubscribes Options: Contains an array with the following object properties

  | Parameter  | Description                                                                                                      |
  |:-----------|:-----------------------------------------------------------------------------------------------------------------|
  | address    | Valid email address                                                                                              |
  | tag        | Tag to unsubscribe from, use * to unsubscribe an address from all domain’s correspondence (optional, default: *) |
  | tags       | Array with tags to unsubscribe from |
  | created_at | Timestamp of a bounce event in RFC2822 format (optional, default: current time)                                  |

  Promise returns:

  ```JS
  {
    message: "1 address has been added to the unsubscribes table"
  }
  ```
   - #### Unsubscribe from one tag
      ```js
      mg.suppressions.create('foobar.example.com', 'unsubscribes', {address: 'bob@example.com', tag: 'your_tag_to_unsubscribe']})
        .then(msg => console.log(msg)) // logs response data
        .catch(err => console.error(err)); // logs any error
      ```
      Promise returns:

      ```JS
      {
        message: "1 address has been added to the unsubscribes table"
      }
      ```
  - #### Unsubscribe from particular tags
      ```js
      mg.suppressions.create('foobar.example.com', 'unsubscribes', [{address: 'bob@example.com', tags: ['your_tag_to_unsubscribe', 'another_tag_to_unsubscribe']}])
        .then(msg => console.log(msg)) // logs response data
        .catch(err => console.error(err)); // logs any error
      ```
      Promise returns:

      ```JS
      {
        message: "1 address has been added to the unsubscribes table"
      }
      ```

- #### Complaints Example:

  ```js
  mg.suppressions.create('foobar.example.com', 'complaints', [{address: 'bob@example.com'}])
    .then(msg => console.log(msg)) // logs response data
    .catch(err => console.error(err)); // logs any error
  ```

  Complaints Options: Contains an array with the following object properties

  | Parameter  | Description                                                                                                      |
  |:-----------|:-----------------------------------------------------------------------------------------------------------------|
  | address    | Valid email address                                                                                              |
  | created_at | Timestamp of a bounce event in RFC2822 format (optional, default: current time)                                  |

  Promise returns:

  ```JS
  {
    message: "1 address has been added to the complaints table"
  }
  ```

• destroy

`mg.suppressions.destroy(domain, suppressionType, address)`

- #### Bounces Example:

  ```JS
  mg.suppressions.destroy('foobar.example.com', 'bounces', 'bob@example.com')
    .then(msg => console.log(msg)) // logs response data
    .catch(err => console.error(err)); // logs any error
  ```

  Promise returns:

  ```JS
  {
    message: "Bounced address has been removed",
    value: "",
    address: "bob@example.com",
    status: 200
  }
  ```

- #### Unsubscribes Example:

  ```js
  mg.suppressions.destroy('foobar.example.com', 'unsubscribes', 'bob@example.com')
    .then(msg => console.log(msg)) // logs response data
    .catch(err => console.error(err)); // logs any error
  ```

  Promise returns:

  ```JS
  {
    message: 'Unsubscribe event has been removed',
    value: '',
    address: 'bob@example.com',
    status: 200
  }
  ```

- #### Complaints Example:

  ```js
  mg.suppressions.destroy('foobar.example.com', 'complaints', 'bob@example.com')
    .then(msg => console.log(msg)) // logs response data
    .catch(err => console.error(err)); // logs any error
  ```

  Promise returns:

  ```JS
    message: 'Spam complaint has been removed',
    value: '',
    address: 'bob@example.com',
    status: 200
  ```

Webhooks

• list

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

open: { 'url': 'http://requestb.in' },
click: { 'url': 'http://requestb.in' },
bounce: { 'url': 'http://requestb.in' },
deliver: { 'url': 'http://requestb.in' },
drop: { 'url': 'http://requestb.in' },
spam: { 'url': 'http://requestb.in' },
unsubscribe: { 'url': 'http://requestb.in' },
click: { 'url': 'http://requestb.in' },
open: { 'url': 'http://requestb.in' },

• get

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

'open': { 'url': 'http://requestb.in', 'urls': ['trackclick.com'] }

• create

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

'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in'] }

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

'code': '500',
'message': 'Hi!'

• update

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

'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in'] }

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

'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in', 'http://requestb1.in'] }

• destroy

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

'open': { 'url': 'http://requestb.in', 'urls': ['http://requestb.in']}

Routes

• list

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

{
  actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ],
  created_at: 'Mon, 26 Oct 2015 03:56:51 GMT',
  description: 'sample',
  expression: 'match_recipient(".*@example.com")',
  id: '562da483125730608a7d1719',
  priority: 0
}

• get

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

actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ],
created_at: 'Mon, 26 Oct 2015 03:56:51 GMT',
description: 'sample',
expression: 'match_recipient(".*@example.com")',
id: '562da483125730608a7d1719',
priority: 0

• create

priority: 0,
description: 'sample',
expression: 'match_recipient(".*@example.org")',
action: ['forward("http://myhost.com/messages/")', 'stop()']
    })
    .then(data => console.log(data)) // logs response body
    .catch(err => console.error(err)); // logs any error

actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ],
created_at: 'Mon, 26 Oct 2015 03:56:51 GMT',
description: 'sample',
expression: 'match_recipient(".*@example.com")',
id: '562da483125730608a7d1719',
priority: 0

• update

priority: 0,
description: 'sample',
expression: 'match_recipient(".*@example.org")',
action: ['forward("http://myhost.com/messages/")', 'stop()']
    })
    .then(data => console.log(data)) // logs response body
    .catch(err => console.error(err)); // logs any error

actions: [ 'forward("http://myhost.com/messages/")', 'stop()' ],
created_at: 'Mon, 26 Oct 2015 03:56:51 GMT',
description: 'sample',
expression: 'match_recipient(".*@example.com")',
id: '562da483125730608a7d1719',
message: 'Route has been updated',
priority: 0

• destroy

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

id: '562da483125730608a7d1719',
message: 'Route has been deleted'

Validation

• get

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

address: 'alice@example.com',
did_you_mean: null,
is_valid: false,
parts: {
   display_name: null,
    domain: null,
    local_part: null
}

Multiple validation

• create

try {
  const file = {
    filename: 'test.csv',
    data: await fsPromises.readFile(filepath)
  };

  const validateBulkResult = await mg.validate.multipleValidation.create('name_of_the_list', { file });
  console.log('validateBulkResult', validateBulkResult);
} catch (error) {
  console.error(error);
}

"id": "name_of_the_list",
"message": "The validation job was submitted."

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

"jobs": [
  {
    "created_at": 1643965937,
    "download_url": {
      "csv": "csv-url",
      "json": "json-url"
    },
    "id": "name_of_the_list",
    "quantity": 40,
    "records_processed": 40,
    "status": "uploaded",
    "summary": {
      "result": {
        "catch_all": 0,
        "deliverable": 0,
        "do_not_send": 0,
        "undeliverable": 0,
        "unknown": 40
      },
      "risk": { "high": 0, "low": 0, "medium": 0, "unknown": 40 }
    }
  }
],
"paging": {
  "first": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=first&pivot=",
  "last": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=last&pivot=",
  "next": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=next&pivot=b4808b5b-1111-2222-3333-6cd0b63f41ea",
  "prev": "https://api.mailgun.net/v4/address/validate/bulk?limit=100&page=prev&pivot="
},
"total": 1

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

"created_at": 1643965937,
"download_url": {
  "csv": "csv-url",
  "json": "json-url"
},
"id": "name_of_the_list",
"quantity": 40,
"records_processed": 40,
"responseStatusCode": 200,
"status": "uploaded",
"summary": {
  "result": {
    "catch_all": 0,
    "deliverable": 0,
    "do_not_send": 0,
    "undeliverable": 0,
    "unknown": 40
  },
  "risk": { "high": 0, "low": 0, "medium": 0, "unknown": 40 }
}

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

body: "Validation job canceled.",
status: 200

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

{
  access_level: 'readonly',
  address: 'noreply@sample.com',
  created_at: 'Wed, 27 Oct 2021 21:59:21 -0000',
  description: '',
  members_count: 0,
  name: '',
  reply_preference: 'list'
}

• get

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

access_level: 'readonly',
address: 'noreply@sample.com',
created_at: 'Thu, 28 Oct 2021 00:16:56 -0000',
description: '',
members_count: 0,
name: '',
reply_preference: 'list'

• create

address: 'reply@sample.com',
name: 'Reply Address', // optional, modifiable on website
description: 'Mailing lists for repliable address', // optional, modifiable on website
access_level: 'readonly', // optional, modifiable on website
reply_preference: 'list', // optional, modifiable on website
    })
    .then(data => console.log(data)) // logs response body
    .catch(err => console.error(err)); // logs any error

access_level: 'readonly',
address: 'reply@sample.com',
created_at: 'Thu, 28 Oct 2021 03:12:17 -0000',
description: 'Mailing lists for repliable address',
members_count: 0,
name: 'Reply Address',
reply_preference: 'list'

• update

address: 'foo@sample.com',
name: 'Foo', // optional, modifiable on website
description: 'Foo bar bat', // optional, modifiable on website
access_level: 'members', // optional, modifiable on website
reply_preference: 'sender', // optional, modifiable on website
    })
    .then(data => console.log(data)) // logs response body
    .catch(err => console.error(err)); // logs any error

access_level: 'members',
address: 'foo@sample.com',
created_at: 'Thu, 28 Oct 2021 03:21:15 -0000',
description: 'Foo bar bat',
members_count: 0,
name: 'Foo',
reply_preference: 'sender'

• destroy

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

address: 'foo@sample.com',
message: 'Mailing list has been removed'

Mailing list members

• listMembers

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

{
  address: 'foo@bar.com',
  name: 'Jane Doe',
  subscribed: true,
  vars: { age: 50 }
}

• getMember

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

address: 'foo@bar.com',
name: 'Jane Doe',
subscribed: true,
vars: { age: 50 }

• createMember

address: 'bat@bar.com',
name: 'John Smith', // optional, modifiable on website
vars: {hobby: "chess"}, // optional, modifiable on website
subscribed: 'no', // optional, modifiable on website
upsert: 'yes', // optional, choose yes to insert if not exist, or update it exist
    })
    .then(data => console.log(data)) // logs response body
    .catch(err => console.error(err)); // logs any error

address: 'bat@bar.com',
name: 'John Smith',
subscribed: false,
vars: { hobby: 'chess' }

• createMembers

members: [
  {
    address: "bot1@foobar.com",
    name: "Bot1 Superbot",
    vars: {location: "loc1"},
    subscribed: true,
  },
  {
    address: "bot2@foobar.com",
    name: "Bot2 Superbot",
    vars: {location: "loc2"},
    subscribed: false,
  },
],
upsert: "yes",
    })
    .then(data => console.log(data)) // logs response body
    .catch(err => console.error(err)); // logs any error

list: {
  access_level: 'readonly',
  address: 'reply@sample.com',
  created_at: 'Thu, 28 Oct 2021 03:21:15 -0000',
  description: 'For reply purpose',
  members_count: 2,
  name: 'Reply',
  reply_preference: 'list'
},
message: 'Mailing list has been updated',
'task-id': '575b943c37a211ec8a520242ac11000a'

• updateMember

address: 'bot0@barfoo.com',
name: 'Bot0 Normalbot', // optional, modifiable on website
vars: {location: "space"},
subscribed: false,
    })
    .then(data => console.log(data)) // logs response body
    .catch(err => console.error(err)); // logs any error

address: 'bot0@barfoo.com',
name: 'Bot0 Normalbot',
subscribed: false,
vars: { location: 'space' }

• destroyMember

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

member: { address: 'bot2@foobar.com' },
message: 'Mailing list member has been deleted'

Subaccounts

• list

.then(subaccounts => console.log(subaccounts)) // logs array of subaccounts
.catch(err => console.error(err)); // logs any error

{ id: "XYZ", name: "test.subaccount1", status: "open" },
{ id: "YYY", name: "test.subaccount2", status: "open" }

• get

.then(subaccount => console.log(subaccount)) // logs subaccount object
.catch(err => console.error(err)); // logs any error

• create

.then(msg => cons