diff --git a/docs/resources/messageEvents.md b/docs/resources/messageEvents.md new file mode 100644 index 0000000..b0d0892 --- /dev/null +++ b/docs/resources/messageEvents.md @@ -0,0 +1,60 @@ +# Message Events + +This library provides easy access to the [Message Events](https://www.sparkpost.com/api#/reference/message-events/) resource. + +## Methods +* **search(params, callback)** + Search for message events using the given parameters (NOTE: all params are optional): + * `params.bounce_classes` - list of [bounce classes](https://support.sparkpost.com/customer/portal/articles/1929896) + * `params.campaign_ids` - campaign IDs + * `params.events` - event types + * `params.friendly_froms` - 'friendly' from addressess + * `params.from` - time lower bound (see below for date/time format details) + * `params.message_ids` - message IDs + * `params.page` - results page number + * `params.per_page` - number of results per page + * `params.reason` - bounce reason with '%' wildcards (see below for example) + * `params.recipients` - recipient email addresses + * `params.template_ids` - template IDs + * `params.timezone` - timezone for `from` and `to` params ([reference](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) + * `params.to` - time upper bound (see below for date/time format details) + * `params.transmission_ids` - transmission IDs + +## Date/Time Parameter Format + +The `from` and `to` search parameters accept datestamps of the form: + + `YYYY-MM-DDTHH:MM` + +For example: `2016-11-14T16:15`. + +Note: timestamps are expressed in the timezone specified by the `timezone` parameter or UTC by default. + +## Examples + +This example code retrieves up to 5 'invalid recipient' bounce events from the first 2 days of 2016. + +```js +var SparkPost = require('sparkpost'); +var client = new SparkPost('YOUR_API_KEY'); +var searchParams = { + from: '2016-01-01T00:00', + to: '2016-01-02T23:59', + page: 1, + per_page: 5, + events: ['bounce', 'out_of_band'], + bounce_classes: [10] +}; + +client.messageEvents.search(searchParams, function(err, res) { + if(err) { + console.log(err); + return; + } + + console.log(data.body); +}); + +``` + +Check out all the examples provided [here](/examples/messageEvents). diff --git a/examples/messageEvents/all_messageEvents.js b/examples/messageEvents/all_messageEvents.js new file mode 100644 index 0000000..5ad4ff3 --- /dev/null +++ b/examples/messageEvents/all_messageEvents.js @@ -0,0 +1,15 @@ +'use strict'; + +var key = 'YOURAPIKEY' + , SparkPost = require('sparkpost') + , client = new SparkPost(key); + +client.messageEvents.search({}, function(err, res) { + if (err) { + console.log(err); + } else { + console.log(res.body); + console.log('Congrats you can use our SDK!'); + } +}); + diff --git a/examples/messageEvents/search_campaignClicks.js b/examples/messageEvents/search_campaignClicks.js new file mode 100644 index 0000000..82b9e79 --- /dev/null +++ b/examples/messageEvents/search_campaignClicks.js @@ -0,0 +1,19 @@ +'use strict'; + +var key = 'YOURAPIKEY' + , SparkPost = require('sparkpost') + , client = new SparkPost(key) + , searchParams = { + events: 'click', + campaign_ids: 'monday_mailshot' + }; + +client.messageEvents.search(searchParams, function(err, res) { + if (err) { + console.log(err); + } else { + console.log(res.body); + console.log('Congrats you can use our SDK!'); + } +}); + diff --git a/examples/messageEvents/search_messageEvents.js b/examples/messageEvents/search_messageEvents.js new file mode 100644 index 0000000..c446367 --- /dev/null +++ b/examples/messageEvents/search_messageEvents.js @@ -0,0 +1,23 @@ +'use strict'; + +var key = 'YOURAPIKEY' + , SparkPost = require('sparkpost') + , client = new SparkPost(key) + , searchParams = { + from: '2016-01-01T00:00', + to: '2016-01-02T23:59', + page: 1, + per_page: 5, + events: ['bounce', 'out_of_band'], + bounce_classes: [10] + }; + +client.messageEvents.search(searchParams, function(err, res) { + if (err) { + console.log(err); + } else { + console.log(res.body); + console.log('Congrats you can use our SDK!'); + } +}); + diff --git a/lib/messageEvents.js b/lib/messageEvents.js new file mode 100644 index 0000000..e46f763 --- /dev/null +++ b/lib/messageEvents.js @@ -0,0 +1,38 @@ +'use strict'; + +var api = 'message-events'; + +/* + * "Class" declaration, Message Events API exposes one function: + * - search: retrieves list of message events according to given params + */ +module.exports = function (client) { + return { + search: function(parameters, callback) { + var arrayParams = [ + 'bounce_classes', + 'campaign_ids', + 'events', + 'friendly_froms', + 'message_ids', + 'recipients', + 'template_ids', + 'transmission_ids' + ] + , options; + + arrayParams.forEach(function(paramname) { + if (Array.isArray(parameters[paramname])) { + parameters[paramname] = parameters[paramname].toString(); + } + }); + + options = { + uri: api + , qs: parameters + }; + client.get(options, callback); + } + }; +}; + diff --git a/lib/sparkpost.js b/lib/sparkpost.js index 2186c50..0f2ce9f 100644 --- a/lib/sparkpost.js +++ b/lib/sparkpost.js @@ -61,6 +61,7 @@ var SparkPost = function(apiKey, options) { this.templates = require('./templates')(this); this.transmissions = require('./transmissions')(this); this.webhooks = require('./webhooks')(this); + this.messageEvents = require('./messageEvents')(this); }; SparkPost.prototype.request = function( options, callback ) { diff --git a/test/spec/messageEvents.spec.js b/test/spec/messageEvents.spec.js new file mode 100644 index 0000000..e26aee9 --- /dev/null +++ b/test/spec/messageEvents.spec.js @@ -0,0 +1,71 @@ +var chai = require('chai') + , expect = chai.expect + , sinon = require('sinon') + , sinonChai = require('sinon-chai'); + +chai.use(sinonChai); + +describe('Message Events Library', function() { + var client, templates; + + beforeEach(function() { + client = { + get: sinon.stub().yields() + }; + + messageEvents = require('../../lib/messageEvents')(client); + }); + + describe('search Method', function() { + it('should call client get method with the appropriate parameters', function(done) { + var options = { + bounce_classes: '10,50', + campaign_ids: 'test_campaign', + events: 'bounce', + friendly_froms: 'bob@example.com', + from: '2015-11-14T16:15', + message_ids: '0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e', + page: 1, + per_page: 5, + reason: '%5.2.0%', + recipients: 'jim@example.com', + template_ids: 'newsletter_template', + timezone: 'America/New_York', + to: '2016-11-14T16:15', + transmission_ids: '65832150921904138' + }; + messageEvents.search(options, function(err, data) { + Object.keys(options).forEach(function(key) { + expect(client.get.firstCall.args[0].qs).to.have.property(key).and.equal(options[key]); + }); + done(); + }); + }); + + it('should accept arrays as parameters where appropriate', function(done) { + var arroptions = { + bounce_classes: [10,50], + campaign_ids: ['campaign1', 'campaignTwo'], + events: ['bounce', 'out_of_band'], + friendly_froms: ['bob@example.com', 'jim@example.com'], + message_ids: ['0e0d94b7-9085-4e3c-ab30-e3f2cd9c273e', '338ac622-4321-5678-0123456789'], + recipients: ['jim@example.com', 'bob@example.com'], + template_ids: ['newsletter_template', 'newsflash_template'], + transmission_ids: ['65832150921904138', '54673829032039839'], + page: 1, + per_page: 5, + timezone: 'America/New_York' + }; + messageEvents.search(arroptions, function(err, data) { + Object.keys(arroptions).forEach(function(key) { + var opt = arroptions[key] + , firstCallQS = client.get.firstCall.args[0].qs; + if (Array.isArray(opt)) { + expect(firstCallQS).to.have.property(key).and.equal(opt.toString()); + } + }); + done(); + }); + }); + }); +});