mailgun-node-js v2.1.2

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
  • Methods
  • Browser Demo
  • Examples
• Development
  • Requirements
  • Build
  • Tests
  • Release Process

Documentation

Install

• Requires node.js >= 4.x

Install mailgun.js with:

npm install mailgun.js

Setup Client

Next, require the module and instantiate a mailgun client by calling mailgun.client with basic auth credentials (username: 'api', key: 'key-yourkeyhere').

var mailgun = require('mailgun.js');
var mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});

To use validate and parse methods, you must additionally include public_key. If you're using only those methods, key can be an empty string.

var mg = mailgun.client({
  username: 'api',
  key: process.env.MAILGUN_API_KEY || '',
  public_key: process.env.MAILGUN_PUBLIC_KEY || 'pubkey-yourkeyhere'
});

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.

• messages
  • create
• domains
  • list
  • get
  • create
  • destroy
  • getTracking
  • updateTracking
• events
  • get
• stats
  • getDomain
  • getAccount
• suppressions
  • list
  • get
  • create
• webhooks
  • list
  • get
  • create
  • update
  • destroy
• routes
  • list
  • get
  • create
  • update
  • destroy
• validate
  • get
• parse
  • get

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

messages

create

mg.messages.create(domain, data) - api docs

HTML/TEXT Example:

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.log(err)); // logs any error

MIME Example:

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.log(err)); // logs any error

Promise Returns:

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

Options:

domains

list

mg.messages.list(query) - api docs

Example:

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

Promise Returns: array of Domain instances

[{
  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
}]

Options

get

mg.messages.get()

Example:

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

Promise Returns: Domain instance

{
  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
}

create

mg.domains.create(data)

Example:

mg.domains.create({name: 'foobar.example.com'})
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.log(err)); // logs any error

Options:

Promise Returns: Domain instance

{
  created_at: 'Sun, 19 Oct 2014 18:49:36 GMT',
  name: 'foobar.example.com',
  receiving_dns_records: [{
      "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"
    }],
  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@foobar.example.com',
  smtp_password: 'password',
  spam_action: 'disabled',
  state: 'unverified',
  type: 'custom',
  wildcard: false
}

destroy

mg.domains.destroy(domain)

Example:

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

Promise Returns:

{
  message: "Domain has been deleted"
}

getTracking

mg.domains.getTracking(domain)

Example:

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

Promise Returns:

{
  "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"
  }
}

updateTracking

mg.domains.updateTracking(domain, trackingType, data)

Open Tracking Example:

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

Open Tracking Options

Promise Returns:

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

Click Tracking Example:

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

Click Tracking Options

Promise Returns:

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

Unsubscribe Tracking Example:

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.log(err)); // logs any error

Unsubscribe Tracking Options

Promise Returns:

{
  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"
  }
}

events

get

mg.events.get(domain, query)

Example:

mg.events.get('foobar.example.com', { page: 'mypageid' })
  .then(data => console.log(data.items)) // logs array of event objects
  .catch(err => console.log(err)); // logs any error

Options:

Promise Returns: items (array of event objects), pages (paging keys grouped by id)

{
 items: [{
    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' }
  }
}

stats

Stats Options

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

getDomain

mg.stats.getDomain(domain, query)

Example:

mg.stats.getDomain('foobar.example.com', {event: ['delivered', 'accepted', 'failed', 'complained']})
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.log(err)); // logs any error

Promise Returns:

{
  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

mg.stats.getDomain(domain, query)

Example:

mg.stats.getDomain('foobar.example.com', {event: ['delivered', 'accepted', 'failed', 'complained']})
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.log(err)); // logs any error

Promise Returns:

{
  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

mg.suppressions.list(domain, suppressionType, query)

Bounces Example:

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

Unsubscribes Example:

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

Complaints Example:

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

Promise Returns:

{
  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

mg.suppressions.get(domain, suppressionType, address)

Bounces Example:

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

Unsubscribes Example:

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

Complaints Example:

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

Options:

Promise Returns:

{
  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, array)

Bounces Example:

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

Bounces Options: Contains an array with the following object properties

Promise Returns:

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

Unsubscribes Example:

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

Unsubscribes Options: Contains an array with the following object properties

Promise Returns:

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

Complaints Example:

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

Complaints Options: Contains an array with the following object properties

Promise Returns:

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

webhooks

list

mg.webhooks.list(domain, query)

Example:

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

Promise Returns:

{
  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

mg.webhooks.get(domain, id)

Example:

mg.webhooks.get('foobar.example.com', 'open') // bounce, deliver, drop, spam, unsubscribe, click, open
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.log(err)); // logs any error

Promise Returns:

{
  'open': { 'url': 'http://requestb.in' }
}

create

mg.webhooks.create(domain, id, data, test)

Example:

mg.webhooks.create('foobar.example.com', 'open', 'http://requestb.in') // bounce, deliver, drop, spam, unsubscribe, click, open
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.log(err)); // logs any error

Promise Returns:

{
  'open': { 'url': 'http://requestb.in' }
}

Test Webhook Example:

mg.webhooks.get('foobar.example.com', 'open', 'http://requestb.in', true) // bounce, deliver, drop, spam, unsubscribe, click, open
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.log(err)); // logs any error

Promise Returns:

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

update

mg.webhooks.update(domain, id, url, test)

Example:

mg.webhooks.update('foobar.example.com', 'open', 'http://requestb.in') // bounce, deliver, drop, spam, unsubscribe, click, open
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.log(err)); // logs any error

Promise Returns:

{
  'open': { 'url': 'http://requestb.in' }
}

destroy

mg.webhooks.destroy(domain, id)

Example:

mg.webhooks.update('foobar.example.com', 'open') // bounce, deliver, drop, spam, unsubscribe, click, open
  .then(msg => console.log(msg)) // logs response data
  .catch(err => console.log(err)); // logs any error

Promise Returns:

{
  'open': { 'url': 'http://requestb.in' }
}

routes

list

mg.routes.list(query)

Example:

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

Promise Returns: response body

[
  {
    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

mg.routes.get(id)

Example:

mg.routes.get('562da483125730608a7d1719')
  .then(data => console.log(data)) // logs response body
  .catch(err => console.log(err)); // logs any error

Promise Returns: response body

{
  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

mg.routes.create(options)

Example:

mg.routes.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.log(err)); // logs any error

Promise Returns: response body

{
  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

mg.routes.update(id, options)

Example:

mg.routes.update('562da483125730608a7d1719', {
    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.log(err)); // logs any error

Promise Returns: response body

{
  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

mg.routes.destroy(id)

Example:

mg.routes.destroy('562da483125730608a7d1719')
  .then(data => console.log(data)) // logs response body
  .catch(err => console.log(err)); // logs any error

Promise Returns: response body

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

validate

get

mg.validate.get(address)

Example:

mg.validate.get('alice@example.com')
  .then(data => console.log(data)) // logs response body
  .catch(err => console.log(err)); // logs any error

Promise Returns: response body

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

parse

get

mg.parse.get(addresses, enableDnsEspChecks)

Example:

mg.parse.get('Alice <alice@example.com>, example.com', true)
  .then(data => console.log(data)) // logs response body
  .catch(err => console.log(err)); // logs any error

Promise Returns: response body

{
  parsed: [],
  unparseable: [
    'Alice <alice@example.com>',
    'example.com'
  ]
}

Browser Demo

For this demo to work, you'll need to install and run http-proxy locally. Install it with:

npm install -g http-proxy

Then run the following command from the mailgun-js directory:

http-server -p 4001 --proxy="https://api.mailgun.net"

Demo should be up and running at http://0.0.0.0:4001/examples/

Development

Requirements

• Requires node.js >= 4.x

Install node dependencies with:

npm install

Build

npm run build

Tests

npm run tests

Watch tests with

npm run watch-tests

Release Process

Releases occur after feature branches have been tested and merged into master.

First, checkout master and pull the latest commits.

git checkout master
git pull

Next, determine semantic version bump (major/minor/patch). Then run npm version with the appropriate keyword.

npm version patch -m "chore(release): added %s"

Other examples:

npm version major -m "chore(release): added %s"
npm version minor -m "chore(release): added %s"
npm version patch -m "chore(release): added %s"

TODO

• add missing services
  • Lists
    • lists.list(query)
    • list.get(address)
    • list.create(data)
    • list.update(address, data)
    • list.destroy(address)
    • lists.listMembers(address, query)
    • list.getMember(address, memberAddress)
    • list.createMember(address, data) (singe & json batch upload)
    • list.updateMember(address, memberAddress, data)
    • list.updateMember(address, memberAddress, data)
    • list.destroyMember(address, memberAddress)
• add browser demo to heroku