Context.IO Email API version 2.0

Powering real email integration

Email is not broken. It's more pervasive than ever as a way to conduct business relationships, share documents revisions and discuss to-dos on important projects. What is broken though is using a standard email client to manage all of this.

Email alternatives do not solve this problem - they force entire teams to adopt technologies that require a behavioural and cultural shift to work, and they shut off interaction with outside tools.

We believe in a world where you can use the tool that works best for you without needing the rest of the world to use it too.

We're building the foundation to make this happen: an API that makes it easy for developers to tap into the data contained in their users mailboxes and embed it seamlessly in their application. We're bringing email out of the inbox.

What's new in 2.0?

Where should we start? We integrated much requested functionality and while we were at it, we cleaned it up and made it RESTful. Here are the key changes:

WebHooks: rule-based notifications pushed to your app

No need to schedule cron jobs polling Context.IO to look for new content, you can now set WebHooks and your app will be notified about new messages. WebHooks are great to follow a specific thread, be notified of message with specific subjects or senders, track when a message is labeled in a special way or simply get notified about incoming emails.

Better interactions with threads

Functions around threads have been improved to make it much easier to retrieve threads for a contact or for a given message. Also, threads list now includes information about messages in the thread in addition to files and contacts as they did in 1.1.

Treat mailboxes as rich address books

Pull Contacts from mailboxes and build contact-based applications that leverage metrics such as message counts and latest sent/received dates.

Filter by and creating folders (or Gmail labels)

Folders can now be used as a filter when obtaining lists of messages, threads or files. It's also possible to create folders for your app in the user's email account.

Treat multiple IMAP accounts as one

Everyone has an email account, and lots of people have more than one. If that's the case for the users of your app, Context.IO makes it pretty easy to merge different mailboxes and treat them as one when getting data from them.

The top-level Accounts resource is meant as the representation of a user of your app and each Account can have many Sources. Whenever you make a call on a given Account, data from all sources tied to this account will be included in the results.

Trigger syncs when desired

You now have better control over one simple and very important task: syncing the index of a mailbox with new content for that mailbox on the email server.

If an account has more than one source (see point above), you can sync a specific source or sync every source in one single call.

Move messages between folders

Want to move your messages from one folder to another? For example, from a "to-do" folder to a "completed" folder? This is now possible in 2.0.

Expose complete message headers and flags

Use our headers call to get a complete list of headers for a given message.

Get the body for multiple messages at once

When listing messages, it is now possible to include the body of the messages in the response by setting the include_body parameter to 1. See message list filters.

RESTful API design

For each mailbox added under your API key, Context.IO 2.0 exposes 5 major resources: Messages, Threads, Files, Contacts and WebHooks. Also, gone are the error messages embedded in the response body. When something goes wrong, you now get the appropriate Server Error 5xx or Client Error 4xx depending on who messed up.

If you're using our awesome client librairies, you'll see these changes are mostly transparent.

Explore our calls before you start building

Our console now features a shiny new "explore" tab that breaks down all of our resources and allows you to test all of our calls before you start heads-down development.

Getting an API key

Sign-up here to get your key and start building.

FAQ

What kind of mailboxes can be accessed?

Anything that can be accessed via IMAP, you can access via our API.

Do you need to know the usernames and passwords of mailboxes?

Not if the mailbox supports OAuth over IMAP. At this time, the only email servers that support OAuth over IMAP is Google (both on Gmail and Google Apps accounts). In other cases, yes. Our API is like an email client, we need to be able to open an authenticated connection to extract the information.

Can I delete emails through your API?

Yes, see the DELETE method on a message.

Can I send emails?

No. If you don't want to use your own SMTP server, there are great services for email delivery like Mailgun, CakeMail or Sendgrid.

Privacy and confidentiality

Email contains confidential and private data. When you access your user's mailbox through our API they trust both you and us to treat that data with the highest level of confidentiality.

Our servers do not store anything more than metadata from mailboxes: to, from, cc, dates, subject, folders, name of files attached. Context.IO DOES NOT store message bodies and attachments.