Launch Week Day 5: Introducing Reachability for PHP.Learn More →
mailgun-js
Advanced tools
mailgun-js - npm Package Compare versions
+440
-194
| /*! | ||
| * mailgun-js | ||
| * Copyright(c) 2012 OneLobby <bojan@onelobby.com> | ||
| * Copyright(c) 2012, 2013 OneLobby <bojan@onelobby.com> | ||
| * 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); | ||
| }; | ||
| }; |
+1
-1
@@ -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", |
+37
-256
@@ -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 <me@samples.mailgun.org>', | ||
| 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 <me@samples.mailgun.org>', | ||
| to: 'serobnic@mail.ru', | ||
| 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: '<20121217142109.14542.78348@mydomain.com>' | ||
| } | ||
| ``` | ||
| ### 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: 'mailbox1@mydomain.com' }, | ||
| { size_bytes: 225280, | ||
| created_at: 'Sat, 13 Oct 2012 17:52:28 GMT', | ||
| mailbox: 'mailbox2@mydomain.com' }, | ||
| { size_bytes: null, | ||
| created_at: 'Wed, 12 Dec 2012 19:39:32 GMT', | ||
| mailbox: 'mailbox3@mydomain.com' }, | ||
| { size_bytes: 0, | ||
| created_at: 'Wed, 12 Dec 2012 21:19:57 GMT', | ||
| mailbox: 'mailbox4@mydomain.com' } | ||
| ] | ||
| } | ||
| ``` | ||
| ### 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: 'testmailbox1@mydomain.com' | ||
| } | ||
| ``` | ||
| ### 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._%+-]+@mydomain.com")', | ||
| 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._%+-]+@mydomain.com")', | ||
| 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._%+-]+@mydomain.com")' | ||
| }; | ||
| 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._%+-]+@mydomain.com")', | ||
| 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._%+-]+@mydomain.com")', | ||
| 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
Major refactor
Supply chain riskPackage 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
Improved metrics
- Total package byte prevSize
24782
50.18%- Lines of code
428
100.94%Worsened metrics
- Number of lines in readme file
102
-68.22%- Number of medium supply chain risk alerts
1
Infinity%No dependency changes