Official Node.js client library for the Context.IO Email API

Context.IO - Mailboxes know a lot. Use them.

Context.IO is the missing email API that makes it easy and fast to integrate your user's email data in your application. ContextIO-node is the officiel Node.js client library.

Usage of this library requires you to register for a Context.IO API key. You can get one free here:

ContextIO-node is installed using npm (

  $ npm install contextio

Once you install the contextio package, using it in your code is fairly simple:

  var ContextIO = require('contextio');
  var ctxioClient = new ContextIO.Client({

The Client constructor simply requires your OAuth consumer key and secret. You can also specify the version and endpoint. By default, the client will use the latest stable version of the API (currently 2.0) and respectively.

Instantiating the client while specifying the API version:

  var ContextIO = require('contextio');
  var ctxioClient = new ContextIO.Client('2.0', {

Instantiating the client while specifying the API version and endpoint:

  var ContextIO = require('contextio');
  var ctxioClient = new ContextIO.Client('2.0', '', {

Doing calls to the Context.IO API

Complete documentation is available on and you can also play around with the API using the Context.IO Explorer (, developer account required).

The design of this library follows the URI structure very closely. For example, to call:

GET /2.0/accounts?limit=15

you would do:

ctxioClient.accounts().get({limit:15}, function (errresponse) {
if (err) throw err;

Making it more general, the equivalent of this generic URI:


would be:


Note that if the resource name contains an underscore character (eg. connect_tokens), you can use both connect_tokens() or connectTokens() with this library.

Call parameters are passed as an Object with properties matching parameter name. Parameters for POST or GET work the same: an Object passed as the first argument of the method call.

Your callback function gets 3 arguments:

  1. err Either null or an Error if something went wrong
  2. response An Object representing the HTTP response. It has three properties:
* *body*: `Object`, `Array` or `String` - If Content-Type is `application/json`, the response body is parsed automatically
* *statusCode*: `Number` - The HTTP status code of the response
* *headers*: `Object` - HTTP headers of the response
  1. request An Object mainly useful for debugging purposes
* *host*: `String` - Host part of the URL being called
* *path*: `String` - Path portion of the URL being called
* *method*: `String` - HTTP method of the call
* *headers*: `Object` - HTTP headers of the request

It has been tested on Node.js 0.6.

Please refer to the test files for an example of every single call.