• Homepage
• API Documentation
• Gem Documentation
• Sign Up

Provides a Ruby interface to Context.IO. The general design was inspired by the wonderful aws-sdk gem. You start with an object that represents your account with Context.IO and then you deal with collections within that going forward (see the Usage section).

If you're looking at the Context.IO docs, it is important to note that there are some attributes that've been renamed to be a bit more Ruby-friendly. In general, if the API returns a number meant to be seconds-from-epoch, then it's been converted to return a Time (e.g. updated has changed to updated_at) and a boolean has converted to something with a ? at the end (e.g. HasChildren and initial_import_finished are has_children? and initial_import_finished?, respectively). See the gem docs for a specific class when in doubt.

$ gem install contextio

Or, of course, put this in your Gemfile:

gem 'contextio'

This gem adheres to SemVer. So you should be pretty safe upgrading from 1.0.0 to 1.9.9. Whatever as long as the major version doesn't bump. When the major version bumps, be warned; upgrading will take some kind of effort.

require 'contextio'

contextio = ContextIO.new('your_api_key', 'your_api_secret')

account = contextio.accounts.where(email: 'some@email.com').first

account.email_addresses # ['some@email.com', 'another@email.com']
account.first_name # 'Bruno'
account.suspended? # False

account.messages.where(folder: '\Drafts').each do |m|
  puts m.subject
end

To grab some object you already know the primary key for, you'll use the [] method like you would for a Hash or Array. This is most helpful for accounts, but works for any resource collection.

require 'contextio'

contextio = ContextIO.new('your_api_key', 'your_api_secret')

account = contextio.accounts[some_account_id]
message = account.messages[some_message_id]

This gem is architected to be as lazy as possible. It won't make an HTTP request until you ask it for some data that it knows it needs to fetch. An example might be illustrative:

require 'contextio'

contextio = ContextIO.new('your_api_key', 'your_api_secret')

account = contextio.accounts['1234'] # No request made here.
account.last_name # Request made here.
account.first_name # No request made here.

Note that when it made the request, it stored the data it got back, which included the first name, so it didn't need to make a second request. Asking for the value of any attribute listed in the gem docs will trigger the request.

There are some consistent mappings between the requests documented in the API docs and the methods implemented in the gem.

For collections of resources:

• the object its self sort of represents the collection-level GET (treat it like any other Enumerable).
• #where is how you set up the filters on the collection-level GET.
• #create maps to the collection-level POST or PUT, as appropriate.
• #[] maps to the individual-level GET, but (as mentioned above) is lazy.

For individual resources

• the object its self sort of represents the individual-level GET (but see #[] above).
• #delete maps to the individual-level DELETE.
• #update maps to the individual-level POST (except in a few cases like Message#copy_to and Message#move_to).

Help is gladly welcomed. If you have a feature you'd like to add, it's much more likely to get in (or get in faster) the closer you stick to these steps:

1. Open an Issue to talk about it. We can discuss whether it's the right direction or maybe help track down a bug, etc.
2. Fork the project, and make a branch to work on your feature/fix. Master is where you'll want to start from.
3. Turn the Issue into a Pull Request. There are several ways to do this, but hub is probably the easiest.
4. Make sure your Pull Request includes tests.
5. Bonus points if your Pull Request updates CHANGES.md to include a summary of your changes and your name like the other entries. If the last entry is the last release, add a new ## Unreleased heading.

If you don't know how to fix something, even just a Pull Request that includes a failing test can be helpful. If in doubt, make an Issue to discuss.

Copyright (c) 2012 Context.IO

This gem is distributed under the MIT License. See LICENSE.md for details.