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 official Node.js client library.
Usage of this library requires you to register for a Context.IO API key. You can get one free here: http://context.io/
The 2.0 version of the API will be deprecated in favor of the Lite version of the API. 2.0 will be partially deprecated on June 15, 2018, and disabled altogether on December 15, 2018.
Using Yarn (recommended)
yarn add contextio
npm install contextio --save
Note: This library was written using ES6 syntax. Please use at least Node 6 to ensure proper functionality.
The constructor requires your OAuth consumer key and secret, which you can find by logging in to the CIO Developer Console. You can optionally specify the API version you wish to use. By default, the client will use version Lite.
const ContextIO =const cioClient =
We strongly discourage keeping OAuth credentials in source control. If you ever need to regenerate your consumer secret you can do so on our developer console
The design of this library follows the URI structure very closely. For example, to call:
your function call would be:
Making it more general, the equivalent of this generic URI:
Query parameters are passed in as an object to the method call:
Post parameters are passed the same way:
If an endpoint supports both query params and a post body, you can pass the query params as second object:
If a POST or a PUT only requires query params, you may pass either an empty object or
null for the body:
Certain endpoints, such as
/2.0/accounts/threads will return a complete URL that you can call to access a resource. You can use the
resource() function to call these urls. Parameters are passed as normal.
Your callback function will receive one argument: an object containing the API response. The body will be JSON parsed for all endpoints that return JSON.
Endpoints that return a raw response will return the unparsed body.
2.0/accounts/files/content endpoint will return an object containing the request headers and the unprocessed body. For more information, please visit our documentation for that endpoint.
headers: resheadersbody: resbody
All errors are thrown, so to handle these gracefully you should add a
catch() to your API calls.
The only errors that this client produces occur when it does not have enough information to construct an api call. This can occur when a parent resource identifier is missing or when the api key/secret/version are not being set correctly.
For example, this call would would cause an error to be thrown because there is no
There is no API error handling built in this client and all API errors will be thrown intact. Our documentation can help in understanding error codes and a handy reference for http status codes can be found over at MDN.
Calls that return file data will have a slightly different response shape:
filename: <name of file>headers: <response header object>body: <binary file data>
Tests are written against Jasmine 2.4 and rely on instantiating a client with the
debug option set to true
const cioClient =
This option circumvents the call to
request-promise, the http library that we use. You may find this useful during development as it allows you to see exactly what is being passed to the
If you want to open an issue or PR for this library - go ahead! We'd love to hear your feedback.