mailgun-js - npm Package Compare versions

Comparing version 0.1.1 to 0.2.0

mailgun.js

 /*!
  * mailgun-js
- * Copyright(c) 2012 OneLobby <[e-mail]>
+ * Copyright(c) 2012, 2013 OneLobby <[e-mail]>
  * MIT Licensed
  */
 
-
 var request = require('request');
 
 /**
- * Creates new Mailgun object
+ * Initializes the Mailgun module
  * @param api_key {String} the API Key for the mailgun account
@@ -16,3 +15,3 @@ * @param domain {String} the mailgun domain
  */
-var Mailgun = module.exports = function (api_key, domain) {
+module.exports = function (api_key, domain) {
   if (!api_key) {
@@ -26,229 +25,476 @@ throw new Error('Mailgun "API key" required');
 
-  this.username = 'api'
-  this.api_key = api_key;
-  this.domain = domain;
-  this.protocol = 'https://';
-  this.host = 'api.mailgun.net';
-  this.endpoint = '/v2';
+  var username = 'api';
+  var protocol = 'https://';
+  var host = 'api.mailgun.net';
+  var endpoint = '/v2';
 
-  this.headers = {};
-  var b = new Buffer([this.username, this.api_key].join(':'));
-  this.headers['Authorization'] = "Basic " + b.toString('base64');
-};
+  var headers = {};
+  var b = new Buffer([username, api_key].join(':'));
+  headers['Authorization'] = "Basic " + b.toString('base64');
 
-/**
- * Creates a new email message and sends it using mailgun
- * @param data {Object} the object containing the data to be sent.
- *                      Required parameters are 'to', 'from', and 'text' or 'html'
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.sendMessage = function (data, cb) {
-  if (!data.to) {
-    return cb(new Error('You must include a "to" parameter.'));
-  }
-  if (!data.from) {
-    return cb(new Error('You must include a "from" parameter.'));
-  }
-  if (!data.text && !data.html) {
-    return cb(new Error('You must include a "text" or "html" parameter.'));
-  }
+  /**
+   * The main function that does all the work. The client really shouldn't call this.
+   * @param method {String} HTTP method
+   * @param resource {String} the resource
+   * @param data {Object} the data to be sent in the request
+   * @param cb {Function} callback for the request
+   * @return
+   */
+  function _request(method, resource, data, cb) {
 
-  return this.request('POST', '/messages', data, cb);
-};
+    if (typeof data === 'function' && !cb) {
+      cb = data;
+      data = {};
+    }
 
-/**
- * Lists mailboxes associated with the mailgun account
- * @param data {Object} the optional object containing the GET options 'limit' and 'skip'
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.getMailboxes = function (data, cb) {
-  return this.request('GET', '/mailboxes', data, cb);
-};
+    var getDomain = function () {
+      var d = '/' + domain;
+      //filter out API calls that do not require a domain specified
+      if ((resource.indexOf('routes') >= 0)
+        || (resource.indexOf('lists') >= 0)) {
+        d = '';
+      }
+      return d;
+    };
 
-/**
- * Creates a new mailbox associated with the mailgun account
- * @param data {Object} the object containing the new mailbox name ('mailbox') and new password ('password')
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.createMailbox = function (data, cb) {
-  if (!data.mailbox) {
-    return cb(new Error('You must include name of the mailbox in the \'mailbox\' parameter.'));
-  }
-  if (!data.password) {
-    return cb(new Error('You must include a password for the new mailbox.'));
-  }
+    var url = '';
+    url = url.concat(
+      protocol,
+      username, ':', api_key,
+      '@',
+      host,
+      endpoint,
+      getDomain(),
+      resource);
 
-  return this.request('POST', '/mailboxes', data, cb);
-};
+    var opts = {
+      url: url,
+      method: method,
+      headers: headers,
+      form: data
+    };
 
-/**
- * Deletes a mailbox associated with the mailgun account
- * @param mailbox {String} the mailbox to be deleted
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.deleteMailbox = function (mailbox, cb) {
-  if (!mailbox || typeof mailbox !== 'string') {
-    return cb(new Error('You must include name of the mailbox.'));
+    var responseCb = function (error, response, body) {
+      if (response && (response.headers['content-type'] === 'application/json')) {
+        try {
+          body = JSON.parse(body);
+
+          if (!error && response.statusCode !== 200) {
+            error = new Error(body.message);
+          }
+        } catch (e) {
+
+        }
+      }
+
+      return (cb || Function)(error, response, body);
+    };
+
+    return request(opts, responseCb);
   }
 
-  return this.request('DELETE', '/mailboxes/' + mailbox, cb);
-};
+  function post(path, data, callback) {
+    return _request('POST', path, data, callback);
+  }
 
-/**
- * Updates the mailbox associated with the mailgun account
- * @param data {Object} the object containing the mailbox name ('mailbox') and new password ('password')
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.updateMailbox = function (data, cb) {
-  if (!data.mailbox) {
-    return cb(new Error('You must include name of the mailbox in the \'mailbox\' parameter.'));
+  function get(path, data, callback) {
+    return _request('GET', path, data, callback);
   }
-  if (!data.password) {
-    return cb(new Error('You must include a password for the mailbox.'));
+
+  function del(path, data, callback) {
+    return _request('DELETE', path, data, callback);
   }
 
-  var mailbox = data.mailbox;
-  delete data.mailbox;
+  function put(path, data, callback) {
+    return _request('PUT', path, data, callback);
+  }
 
-  return this.request('PUT', '/mailboxes/' + mailbox, data, cb);
-};
+  return {
+    messages: {
+      /**
+       * Creates a new email message and sends it using mailgun
+       * @param data {Object} the object containing the data to be sent.
+       *                      Required parameters are 'to', 'from', and 'text' or 'html'
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      send: function (data, cb) {
+        if (!data.to) {
+          return (cb || Function)(new Error('You must include a "to" parameter.'));
+        }
+        if (!data.from) {
+          return (cb || Function)(new Error('You must include a "from" parameter.'));
+        }
+        if (!data.text && !data.html) {
+          return (cb || Function)(new Error('You must include a "text" or "html" parameter.'));
+        }
 
+        return post('/messages', data, cb);
+      }
+    },
 
-/**
- * Lists routes associated with the mailgun account
- * @param data {Object} the optional object containing the GET options 'limit' and 'skip'
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.getRoutes = function (data, cb) {
-  return this.request('GET', '/routes', data, cb);
-};
+    mailboxes: {
+      /**
+       * Lists mailboxes associated with the mailgun account
+       * @param data {Object} the optional object containing the GET options 'limit' and 'skip'
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      list: function (data, cb) {
+        return get('/mailboxes', data, cb);
+      },
 
-/**
- * Returns a single route object based on its ID.
- * @param id {String} the route ID
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.getRoute = function (id, cb) {
-  if (!id || typeof id !== 'string') {
-    return cb(new Error('You must include id of the route.'));
-  }
+      /**
+       * Creates a new mailbox associated with the mailgun account
+       * @param data {Object} the object containing the new mailbox name ('mailbox') and new password ('password')
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      create: function (data, cb) {
+        if (!data.mailbox) {
+          return (cb || Function)(new Error('You must include name of the mailbox in the \'mailbox\' parameter.'));
+        }
+        if (!data.password) {
+          return (cb || Function)(new Error('You must include a password for the new mailbox.'));
+        }
 
-  return this.request('GET', '/routes/' + id, cb);
-};
+        return post('/mailboxes', data, cb);
+      },
 
-/**
- * Creates a new route
- * @param data {Object} the object containing the priority, description, expression and action as strings
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.createRoute = function (data, cb) {
-  if (!data.expression) {
-    return cb(new Error('You must include route expression.'));
-  }
-  if (!data.action) {
-    return cb(new Error('You must include route action.'));
-  }
+      /**
+       * Deletes a mailbox associated with the mailgun account
+       * @param mailbox {String} the mailbox to be deleted
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      del: function (mailbox, cb) {
+        if (!mailbox || typeof mailbox !== 'string') {
+          return (cb || Function)(new Error('You must include name of the mailbox.'));
+        }
 
-  return this.request('POST', '/routes', data, cb);
-};
+        return del('/mailboxes/' + mailbox, cb);
+      },
 
-/**
- * Updates a given route by ID. All data parameters optional:
- * this API call only updates the specified fields leaving others unchanged.
- * @param id {String} the route ID
- * @param data {Object} the object containing the priority, description, expression and action as strings
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.updateRoute = function (id, data, cb) {
-  if (!id || typeof id !== 'string') {
-    return cb(new Error('You must include id of the route.'));
-  }
+      /**
+       * Updates the mailbox associated with the mailgun account
+       * @param data {Object} the object containing the mailbox name ('mailbox') and new password ('password')
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      update: function (data, cb) {
+        if (!data.mailbox) {
+          return (cb || Function)(new Error('You must include name of the mailbox in the \'mailbox\' parameter.'));
+        }
+        if (!data.password) {
+          return (cb || Function)(new Error('You must include a password for the mailbox.'));
+        }
 
-  return this.request('PUT', '/routes/' + id, data, cb);
-};
+        var mailbox = data.mailbox;
+        delete data.mailbox;
 
-/**
- * Deletes a route based on the id.
- * @param id {String} the id of the route to be deleted
- * @param cb {Function} callback function accepting error, response and body
- * @type {Function}
- */
-Mailgun.prototype.deleteRoute = function (id, cb) {
-  if (!id || typeof id !== 'string') {
-    return cb(new Error('You must include the id of the route.'));
-  }
+        return put('/mailboxes/' + mailbox, data, cb);
+      }
+    },
 
-  return this.request('DELETE', '/routes/' + id, cb);
-};
+    routes: {
+      /**
+       * Lists routes associated with the mailgun account
+       * @param data {Object} the optional object containing the GET options 'limit' and 'skip'
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      list: function (data, cb) {
+        return get('/routes', data, cb);
+      },
 
-/**
- * The main function that does all the work. The client really shouldn't call this.
- * @param method {String} HTTP method
- * @param resource {String} the resource
- * @param data {Object} the data to be sent in the request
- * @param cb {Function} callback for the request
- * @return
- */
+      /**
+       * Returns a single route object based on its ID.
+       * @param id {String} the route ID
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      get: function (id, cb) {
+        if (!id || typeof id !== 'string') {
+          return (cb || Function)(new Error('You must include id of the route.'));
+        }
 
-Mailgun.prototype.request = function (method, resource, data, cb) {
+        return get('/routes/' + id, cb);
+      },
 
-  var self = this;
+      /**
+       * Creates a new route
+       * @param data {Object} the object containing the priority, description, expression and action as strings
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      create: function (data, cb) {
+        if (!data.expression) {
+          return (cb || Function)(new Error('You must include route expression.'));
+        }
+        if (!data.action) {
+          return (cb || Function)(new Error('You must include route action.'));
+        }
 
-  if (typeof data === 'function' && !cb) {
-    cb = data;
-    data = {};
-  }
+        return post('/routes', data, cb);
+      },
 
-  var getDomain = function() {
-    var d = '/' + self.domain;
-    //filter out API calls that do not require a domain specified
-    if (resource.indexOf('route') >= 0) {
-      d = '';
-    }
-    return d;
-  };
+      /**
+       * Updates a given route by ID. All data parameters optional:
+       * this API call only updates the specified fields leaving others unchanged.
+       * @param id {String} the route ID
+       * @param data {Object} the object containing the priority, description, expression and action as strings
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      update: function (id, data, cb) {
+        if (!data || (typeof data !== 'object')) {
+          return (cb || Function)(new Error('You must include data.'));
+        }
 
-  var url = '';
-  url = url.concat(
-    this.protocol,
-    this.username, ':', this.api_key,
-    '@',
-    this.host,
-    this.endpoint,
-    getDomain(),
-    resource);
+        if (!id || typeof id !== 'string') {
+          return cb(new Error('You must include id of the route.'));
+        }
 
-  var opts = {
-    url: url,
-    method: method,
-    headers: this.headers,
-    form: data
-  };
+        return put('/routes/' + id, data, cb);
+      },
 
-  var responseCb = function (error, response, body) {
-    if (response && (response.headers['content-type'] === 'application/json')) {
-      try {
-        body = JSON.parse(body);
+      /**
+       * Deletes a route based on the id.
+       * @param id {String} the id of the route to be deleted
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      del: function (id, cb) {
+        if (!id || typeof id !== 'string') {
+          return (cb || Function)(new Error('You must include the id of the route.'));
+        }
 
-        if (!error && response.statusCode !== 200) {
-          error = new Error(body.message);
+        return del('/routes/' + id, cb);
+      }
+    },
+
+    lists: {
+      /**
+       * Returns a list of mailing lists under your account.
+       * @param data {Object} the optional object containing the GET options 'address', 'limit' and 'skip'
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      list: function (data, cb) {
+        return get('/lists', data, cb);
+      },
+
+      /**
+       * Returns a single mailing list by a given address.
+       * @param address {String} the mailing list address
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      get: function (address, cb) {
+        if (!address || typeof address !== 'string') {
+          return (cb || Function)(new Error('You must include mailing list address.'));
         }
-      } catch (e) {
 
+        return get('/lists/' + address, cb);
+      },
+
+      /**
+       * Creates a new mailing list.
+       * @param data {Object} the object containing the address, name, description, and access_level as strings
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      create: function (data, cb) {
+        if (!data.address) {
+          return (cb || Function)(new Error('You must include mailing list address.'));
+        }
+
+        return post('/lists', data, cb);
+      },
+
+      /**
+       * Update mailing list properties, such as address, description or name.
+       * @param address {String} mailing list address
+       * @param data {Object} the object containing the address, name, description, and access_level as strings
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      update: function (address, data, cb) {
+        if (!data || (typeof data !== 'object')) {
+          return (cb || Function)(new Error('You must include data.'));
+        }
+
+        if (!address || typeof address !== 'string') {
+          return (cb || Function)(new Error('You must include mailing list address.'));
+        }
+
+        return put('/lists/' + address, data, cb);
+      },
+
+      /**
+       * Deletes a mailing list.
+       * @param address {String} mailing list address
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      del: function (address, cb) {
+        if (!address || typeof address !== 'string') {
+          return (cb || Function)(new Error('You must include mailing list address.'));
+        }
+
+        return del('/lists/' + address, cb);
+      },
+
+      /**
+       * Fetches mailing list stats.
+       * @param address {String} mailing list address
+       * @param cb {Function} callback function accepting error, response and body
+       * @type {Function}
+       */
+      stats: function (address, cb) {
+        if (!address || typeof address !== 'string') {
+          return (cb || Function)(new Error('You must include mailing list address.'));
+        }
+
+        return get('/lists/' + address + '/stats', cb);
+      },
+
+      members: {
+        /**
+         * Fetches the list of mailing list members.
+         * @param listAddress {String} mailing list address
+         * @param data {Object} the optional object containing the GET options 'subscribed', 'limit' and 'skip'
+         * @param cb {Function} callback function accepting error, response and body
+         * @type {Function}
+         */
+        list: function (listAddress, data, cb) {
+          if (!listAddress || typeof listAddress !== 'string') {
+            var last = arguments.length - 1;
+            var callback = (arguments[last] && (typeof arguments[last] === 'function')) ? arguments[last] : Function;
+            return callback(new Error('You must include mailing list address.'));
+          }
+
+          return get('/lists/' + listAddress + '/members', data, cb);
+        },
+
+        /**
+         * Retrieves a mailing list member.
+         * @param listAddress {String} mailing list address
+         * @param memberAddress {String} member address
+         * @param cb {Function} callback function accepting error, response and body
+         * @type {Function}
+         */
+        get: function (listAddress, memberAddress, cb) {
+          var last = arguments.length - 1;
+          var callback = (arguments[last] && (typeof arguments[last] === 'function')) ? arguments[last] : Function;
+          if (!listAddress || typeof listAddress !== 'string') {
+            return callback(new Error('You must include mailing list address.'));
+          }
+
+          if (!memberAddress || typeof memberAddress !== 'string') {
+            return callback(new Error('You must include member address.'));
+          }
+
+          return get('/lists/' + listAddress + '/members/' + memberAddress, cb);
+        },
+
+        /**
+         * Adds a member to the mailing list.
+         * @param listAddress {String} mailing list address
+         * @param data {Object} the object containing the address, name, vars, subscribed and upsert
+         * @param cb {Function} callback function accepting error, response and body
+         * @type {Function}
+         */
+        create: function (listAddress, data, cb) {
+          var last = arguments.length - 1;
+          var callback = (arguments[last] && (typeof arguments[last] === 'function')) ? arguments[last] : Function;
+          if (!data || (typeof data !== 'object')) {
+            return callback(new Error('You must include data.'));
+          }
+
+          if (!listAddress || typeof listAddress !== 'string') {
+            return callback(new Error('You must include mailing list address.'));
+          }
+
+          if (!data.address || typeof data.address !== 'string') {
+            return callback(new Error('You must include member address.'));
+          }
+
+          var params = {};
+          // prepare vars, has to be valid JSON
+          if (data.vars && typeof data.vars === 'object') {
+            for (var key in data) {
+              params[key] = data[key];
+            }
+            params.vars = JSON.stringify(params.vars);
+          }
+          else {
+            params = data;
+          }
+
+          return post('/lists/' + listAddress + '/members', params, cb);
+        },
+
+        /**
+         * Updates a mailing list member with given properties. Won’t touch the property if it’s not passed in.
+         * @param listAddress {String} mailing list address
+         * @param memberAddress {String} member address
+         * @param data {Object} the object containing the address, name, vars, subscribed
+         * @param cb {Function} callback function accepting error, response and body
+         * @type {Function}
+         */
+        update: function (listAddress, memberAddress, data, cb) {
+          var last = arguments.length - 1;
+          var callback = (arguments[last] && (typeof arguments[last] === 'function')) ? arguments[last] : Function;
+
+          if (!listAddress || typeof listAddress !== 'string') {
+            return callback(new Error('You must include mailing list address.'));
+          }
+
+          if (!memberAddress || typeof memberAddress !== 'string') {
+            return callback(new Error('You must include member address.'));
+          }
+
+          if (!data || (typeof data !== 'object')) {
+            return callback(new Error('You must include data to update.'));
+          }
+
+          var params = {};
+          // prepare vars, has to be valid JSON
+          if (data.vars && typeof data.vars === 'object') {
+            for (var key in data) {
+              params[key] = data[key];
+            }
+            params.vars = JSON.stringify(params.vars);
+          }
+          else {
+            params = data;
+          }
+
+          return put('/lists/' + listAddress + '/members/' + memberAddress, params, cb);
+        },
+
+        /**
+         * Delete a mailing list member.
+         * @param listAddress {String} mailing list address
+         * @param memberAddress {String} member address
+         * @param cb {Function} callback function accepting error, response and body
+         * @type {Function}
+         */
+        del: function (listAddress, memberAddress, cb) {
+          var last = arguments.length - 1;
+          var callback = (arguments[last] && (typeof arguments[last] === 'function')) ? arguments[last] : Function;
+          if (!listAddress || typeof listAddress !== 'string') {
+            return callback(new Error('You must include mailing list address.'));
+          }
+
+          if (!memberAddress || typeof memberAddress !== 'string') {
+            return callback(new Error('You must include member address.'));
+          }
+
+          return del('/lists/' + listAddress + '/members/' + memberAddress, cb);
+        }
       }
     }
-
-    return cb(error, response, body);
   };
-
-  return request(opts, responseCb);
-};
+};

package.json

@@ -8,3 +8,3 @@ {
     "keywords": ["email", "mailgun"],
-    "version": "0.1.1",
+    "version": "0.2.0",
     "homepage": "https://github.com/1lobby/mailgun-js",
@@ -11,0 +11,0 @@ "license": "MIT",

README.md

@@ -13,3 +13,3 @@ # mailgun.js
 Most methods take a `data` parameter, which is a Javascript object that would contain the arguments for the Mailgun API.
-All methods take a final parameter callback with three parameters: `error`, `response`, and `body`, exactly like the request callback.
+All methods take a final parameter callback with three parameters: `error`, `response`, and `body`, exactly like the [request](https://github.com/mikeal/request) callback.
 We try to parse the `body` into a javascript object, and return it to the callback as such for easier use and inspection by the client.
@@ -19,10 +19,10 @@ `response.statusCode` will be `200` if everything worked OK. See Mailgun documentation for other (error) response codes.
 
-Currently we only implement the `send message` (non-MIME) API and the `Mailboxes` and `Routes` API's. These would be the most common
+Currently we only implement the `send message` (non-MIME) API and the `Mailboxes`, `Routes`, and `Mailing Lists` API's. These would be the most common
 and practical API's to be programmatically used. Others would be easy to add if needed.
 
 ```javascript
-var Mailgun = require('mailgun-js');
+var api_key = 'key-XXXXXXXXXXXXXXXXXXXXXXX';
+var domain = 'mydomain.mailgun.org';
+var mailgun = require('mailgun-js')(api_key, domain);
 
-var mailgun = new Mailgun('key-...............................', 'mydomain.com');
-
 var data = {
@@ -35,3 +35,3 @@ from: 'Excited User <[e-mail]>',
 
-mailgun.sendMessage(data, function (error, response, body) {
+mailgun.messages.send(data, function (error, response, body) {
   console.log(body);
@@ -41,254 +41,35 @@ });
 
-## Constructor
+## API
 
-### new Mailgun(key, domain);
+All methods take a callback as their last parameter. The callback is called with a Javascript `Error` (if any) and then the `response` and the `body` returned by mailgun. 
+For actual examples see the tests source code. Note that `routes` and `lists` API's do not act on specified mailgun domains and are global for the mailgun account.
 
-Returns a Mailgun object with your Mailgun API key and Mailgun domain set on the object.
+* `mailgun.messages` - Creates a new email message and sends it using mailgun.
+   * `.send(data)` - [send a message](http://documentation.mailgun.net/api-sending.html).
+* `mailgun.mailboxes` - create, update, delete and list [mailboxes](http://documentation.mailgun.net/api-mailboxes.html).
+   * `.list(data)` - list mailboxes. `data` is optional and can contain `limit` and `skip`.
+   * `.create(data)` - create a mailbox. `data` should have `mailbox` name and `password`.
+   * `.update(data)` - update a mailbox given the `mailbox` name. Currently only the `password` can be changed.
+   * `.del(mailbox)` - delete a mailbox given the `mailbox` name.
+* `mailgun.routes` - create, get, update, delete and list [routes](http://documentation.mailgun.net/api-routes.html).
+   * `.list(data)` - list routes. `data` is optional and can contain `limit` and `skip`.
+   * `.get(id)` - get a specific route given the route `id`.
+   * `.create(data)` - create a route. `data` should contain `priority`, `description`, `expression` and `action` as strings.
+   * `.update(id, data)` - update a route given route `id`. All `data` parameters optional. This API call only updates the specified fields leaving others unchanged.
+   * `.del(id)` - delete a route given route `id`.
+* `mailgun.lists` - create, get, update, delete and list [mailing lists](http://documentation.mailgun.net/api-mailinglists.html) and get mailing list stats.
+   * `.list(data)` - list mailing lists. `data` is optional and can contain `address`, `limit` and `skip`.
+   * `.get(address)` - get a specific mailing list given mailing list `address`.
+   * `.create(data)` - create a mailing list. `data` should contain `address`, `name`, `description`, and `access_level` as strings.
+   * `.update(address, data)` - update a mailing list given mailing list `address`.
+   * `.del(address)` - delete a mailing list given mailing list `address`.
+   * `.stats(address)` - fetches mailing list stats given mailing list `address`.
+* `mailgun.lists.members` - create, get, update, delete and list [mailing list members](http://documentation.mailgun.net/api-mailinglists.html).
+   * `.list(listAddress, data)` - list mailing list members. `data` is optional and can contain `subscribed`, `limit` and `skip`.
+   * `.get(listAddress, memberAddress)` - get a specific mailing list member given mailing list address and member address.
+   * `.create(listAddress, data)` - create a mailing list member. `data` should contain `address`, optional member `name`, `subscribed`, `upsert`, and any additional `vars`.
+   * `.update(listAddress, memberAddress, data)` - update a mailing list member with given properties. Won't touch the property if it's not passed in.
+   * `.del(listAddress, memberAddress)` - delete a mailing list member given mailing list address and member address.
 
-## Methods
 
-### mailgun.sendMessage(data, callback)
-
-```javascript
-var data = {
-  from: 'Excited User <[e-mail]>',
-  to: '[e-mail]',
-  subject: 'Hello',
-  text: 'Testing some Mailgun awesomness!'
-};
-
-mailgun.sendMessage(data, function (error, response, body) {
-  console.log(body);
-});
-```
-
-Sample `body` is a javascript object
-
-```
-{
-  message: 'Queued. Thank you.',
-  id: '<[e-mail]>'
-}
-```
-
-### mailgun.getMailboxes(callback)
-
-Gets a list of mailboxes for the domain. Sample `body`:
-
-```
-{
-  total_count: 4,
-  items:
-   [
-     { size_bytes: 167936,
-       created_at: 'Thu, 13 Sep 2012 17:41:58 GMT',
-       mailbox: '[e-mail]' },
-     { size_bytes: 225280,
-       created_at: 'Sat, 13 Oct 2012 17:52:28 GMT',
-       mailbox: '[e-mail]' },
-     { size_bytes: null,
-       created_at: 'Wed, 12 Dec 2012 19:39:32 GMT',
-       mailbox: '[e-mail]' },
-     { size_bytes: 0,
-       created_at: 'Wed, 12 Dec 2012 21:19:57 GMT',
-       mailbox: '[e-mail]' }
-   ]
-}
-```
-
-### mailgun.createMailbox(data, callback)
-
-Creates a new mailbox for the domain.
-
-```javascript
-var data = {
-  mailbox: 'testmailbox1',
-  password: 'password1'
-};
-
-mailgun.createMailbox(data, function (error, response, body) {
-  console.log(body);
-});
-```
-
-Sample `body`:
-
-```
-{
-  message: 'Created 1 mailboxes'
-}
-```
-
-### mailgun.deleteMailbox(mailbox, callback)
-
-Deletes the specified mailbox for the domain.
-
-```javascript
-mailgun.deleteMailbox('testmailbox1', function (error, response, body) {
-  console.log(body);
-});
-```
-
-Sample `body`:
-
-```
-{
-  message: 'Mailbox has been deleted',
-  spec: '[e-mail]'
-}
-```
-
-### mailgun.updateMailbox(data, callback)
-
-Updates the password for a specified mailbox in the the domain.
-
-```javascript
-var data = {
-  mailbox: 'testmailbox1',
-  password: 'newpassword2'
-};
-
-mailgun.updateMailbox(data, function (error, response, body) {
-  console.log(body);
-});
-```
-
-Sample `body`:
-
-```
-{
-  message: 'Password changed'
-}
-```
-
-### mailgun.getRoutes(callback)
-
-Gets all the routes. Note that all `Routes` API methods are not domain-specific. Sample `body`:
-
-```
-{ total_count: 1,
-  items:
-   [
-     {
-       description: 'my route',
-       created_at: 'Fri, 14 Dec 2012 20:46:14 GMT',
-       actions: [ 'forward("http://mydomain.com/mail/receive")' ],
-       priority: 0,
-       expression: 'match_recipient("^[A-Z0-9._%+-][e-mail]")',
-       id: '28cb12345cbd98765e123b84'
-     }
-   ]
-}
-```
-
-### mailgun.getRoute(id, callback)
-
-Returns a single route object based on its ID.
-
-```javascript
-mailgun.getRoute('12cf345d09876d23450211ed', function (error, response, body) {
-  console.log(body);
-});
-```
-
-Sample `body`:
-
-```
-{
-  route:
-   {
-     description: 'my new route!',
-     created_at: 'Mon, 17 Dec 2012 15:21:33 GMT',
-     actions: [ 'forward("http://mydomain.com/mail/receive")' ],
-     priority: 0,
-     expression: 'match_recipient("^[A-Z0-9._%+-][e-mail]")',
-     id: '12cf345d09876d23450211ed'
-   }
-}
-```
-
-### mailgun.createRoute(data, callback)
-
-Creates a new route.
-
-```javascript
-var data = {
-  description: 'my new route!',
-  action: [ 'forward("http://mydomain.com/mail/receive")', 'stop()' ],
-  expression: 'match_recipient("^[A-Z0-9._%+-][e-mail]")'
-};
-
-mailgun.createRoute(data, function (error, response, body) {
-  console.log(body);
-});
-```
-
-Sample `body`:
-
-```
-{
-  message: 'Route has been created',
-  route:
-   {
-     description: 'my new route!',
-     created_at: 'Mon, 17 Dec 2012 15:21:33 GMT',
-     actions: 
-       [ 'forward("http://mydomain.com/mail/receive")',
-         'stop()' ],
-     priority: 0,
-     expression: 'match_recipient("^[A-Z0-9._%+-][e-mail]")',
-     id: '12cf345d09876d23450211ed'
-   }
-}
-```
-
-### mailgun.updateRoute(id, data, callback)
-
-Updates a given route by ID. All data parameters optional.
-This API call only updates the specified fields leaving others unchanged.
-
-```javascript
-var data = {
-  description: 'my new updated route!',
-  action: 'forward("http://mydomain.com/receiveMail")'
-};
-
-mailgun.updateRoute('12cf345d09876d23450211ed', data, function (error, response, body) {
-  console.log(body);
-});
-```
-
-Sample `body`:
-
-```
-{
-  priority: 0,
-  description: 'my new updated route!',
-  created_at: 'Mon, 17 Dec 2012 15:21:33 GMT',
-  expression: 'match_recipient("^[A-Z0-9._%+-][e-mail]")',
-  message: 'Route has been updated',
-  actions: [ 'forward("http://mydomain.com/receiveMail")' ],
-  id: '12cf345d09876d23450211ed'
-}
-```
-
-### mailgun.deleteRoute(id, callback)
-
-Deletes the specified route
-
-```javascript
-mailgun.deleteRoute('12cf345d09876d23450211ed', function (error, response, body) {
-  console.log(body);
-});
-```
-
-Sample `body`:
-
-```
-{
-  message: 'Route has been deleted',
-  id: '12cf345d09876d23450211ed'
-}
-```
-
 ## Tests
@@ -312,3 +93,3 @@
 
-The tests will call Mailgun API, and will send a test email, create mailbox(es) and route(s).
+The tests will call Mailgun API, and will send a test email, create mailbox(es), route(s), mailing list and mailing list member.
 
@@ -323,4 +104,4 @@ ## TODO
 
-Copyright 2012 OneLobby
+Copyright 2012, 2013 OneLobby
 
 Licensed under the MIT License.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

24782

increased by50.18%

Lines of code

428

increased by100.94%

Worsened metrics

Number of lines in readme file

102

decreased by-68.22%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes