Connecting Mailboxes to your App

  1. Your application owns one Context.IO API key
  2. For each user account in your app, you create an account with your API key.
  3. Your users have one or more email accounts. You connect each of them as a source for the corresponding account.

As soon as a mailbox is connected, we create a metadata index of its content starting from the most recent emails which become available from the API within seconds.

The Quick & Easy Way: connect_tokens

You simply add a "connect my mailbox" button to your app and we'll do the rest.

The "Full-Control" Way: API Calls

Control the user flow and simply call our API to create accounts and sources under these accounts.

Using OAuth for Gmail Access

We support OAuth as the preferred way to connect Gmail and Google Apps mailboxes. You can even use your own Google OAuth consumer to make sure users authorize your app explicitly.

API Overview

  • Contacts
  • Files
  • Messages
  • Threads
  • WebHooks

Exposes recipients and senders as people with stats on messages counts and latest sent/received

Example: Get information about jim.bob@widgets.com in mailbox account_id

GET /2.0/accounts/account_id/contacts/jim.bob@widgets.com
{
  emails: [
    "jim.bob@widgets.com"
  ], 
  name: "Jim Bob", 
  thumbnail: "https://secure.gravatar.com/avatar/c9879ab656ee0bd600b6561a9d56af9a?s=50",
  last_received: 1321473684, 
  last_sent: 1322025459, 
  count: 2360
}

Each attachment in a mailbox has a unique id allowing you to query and access them directly.

Example: Get the list of attachments in mailbox account_id with name matching pattern contextio*.pdf

GET /2.0/accounts/account_id/files/?file_name=contextio%2A.pdf
[
  {
    size: 2872244, 
    type: "application/pdf", 
    subject: "In SF/Valley on the week of Nov 14th", 
    date: 1319738087, 
    addresses: {
      from: {
        email: "bruno@widgets.com", 
        name: "Bruno Morency"
      }, 
      to: [
        {
          email: "jim.bob@acme.com", 
          name: "Jim Bob"
        }
      ], 
      cc: [
        {
          email: "sarah-jane@widgets.com", 
          name: "Sarah-Jane Morris"
        }
      ]
    }, 
    file_name: "ContextIO - Overview - 20111016.pdf", 
    body_section: 2, 
    file_id: "4ea9b53e3f757e2c4a000018", 
    supports_preview: true, 
    date_indexed: 1319744830, 
    message_id: "4fa15ed47e747e202d100006", 
    email_message_id: "<CBOEgs7BW6ke6qd7bzRYO@widgets.com>", 
    person_info: {
      bruno@widgets.com: {
	    thumbnail: "https://secure.gravatar.com/avatar/c9879ab656ee0bd600b6561a9d56af9a?s=50"
      }, 
      jim.bob@acme.com: {
        thumbnail: "https://secure.gravatar.com/avatar/c9879ab656ee0bd600b6561a9d56af9a?s=50"
      },
      sarah-jane@widgets.com: {
        thumbnail: "https://secure.gravatar.com/avatar/c9879ab656ee0bd600b6561a9d56af9a?s=50"
      }
    }, 
    file_name_structure: [
      ["ContextIO - Overview","main"], 
      [" - ","boundary"], 
      ["20111016","date"], 
      [".pdf","ext"]
    ]
  },
  ...
]

Query messages by sender/recipients, folder, dates, subject. Move them around. Get their body, flags and complete headers.

Example: Get messages in mailbox account_id received from dominik@widgets.com between Nov 1st and Nov 30th, 2011.

GET /2.0/accounts/account_id/messages/?date_after=1320120000&date_before=1322715599&from=dominik%40widgets.com
[
  {
    date: 1321473684, 
    folders: ["\\Important","[Gmail]/Important"], 
    addresses: {
      from: {
        email: "dominik@widgets.com", 
        name: "Dominik Gehl"
      }, 
      to: [
        {
          email: "bruno@widgets.com", 
          name: "Bruno Morency"
        }
      ]
    }, 
    sources: [
      {
        label: "imap.gmail.com::bruno@widgets.com", 
        resource_url: "https://api.context.io/2.0/accounts/4e0928a03edc0c0b021e6070/sources/imap.gmail.com::bruno@widgets.com"
      }
    ], 
    files: [
      {
        size: 423054, 
        type: "image/jpeg", 
        file_name: "Homepage - v1.jpg", 
        main_file_name: "Homepage - v1", 
        file_name_structure: [
          ["Homepage","main"], 
          [" - ","boundary"], 
          ["v1","version"], 
          [".jpg","ext"]
        ], 
        body_section: 2, 
        file_id: "4ed13ed53f757e257d000002", 
        supports_preview: true
      }
    ], 
    subject: "utilisation de mailboxes / downloads / syncs et API", 
    message_id: "4fa15ed47e747e202d100006", 
    email_message_id: "<CBOEgs7BW6_1RZb=B3i_R9My-Es39heFtke6qd7bzRYO-o=14_A@mail.gmail.com>", 
    gmail_message_id: "132e1658bcda1ccd", 
    gmail_thread_id: "132e1658bcda1ccd", 
    person_info: {
      dominik@widgets.com: {
        thumbnail: "https://secure.gravatar.com/avatar/c9879ab656ee0bd600b6561a9d56af9a?s=50"
      }, 
      bruno@widgets.com: {
        thumbnail: "https://secure.gravatar.com/avatar/4fc965d14ddff2d5c14fca85d5c0dba0?s=50"
      }
    }, 
    date_indexed: 1321491704
  },
  ...
]

Query threads by sender/recipients, folder, dates. Easily get the list of messages in a thread no matter what folder messages are in.

Example: Query mailbox account_id for the thread message message_id is part of.

GET /2.0/accounts/account_id/messages/message_id/thread/
{
  email_message_ids: [
    "<CBOEgs7BW6_1RZb=B3i_R9My-Es39heFtke6qd7bzRYO-o=14_A@mail.gmail.com>", 
    "<6ES149EC.7257501@widgets.com>",
    ...
  ], 
  messages: [
    {
      addresses: {
        from: {
          email: "tom.thompson@gmail.com", 
          name: "Tom Thompson"
        }, 
        to: [
          {
            email: "bruno@widgets.com", 
            name: "Bruno Morency"
          }
        ]
      }, 
      folders: [
        "\\Important", 
        "\\Inbox", 
        "INBOX", 
        "[Gmail]/Important"
      ], 
      date: 1322332272, 
      subject: "Box.net App Mockups", 
      sources: [
        {
          label: "imap.gmail.com::bruno@widgets.com", 
          resource_url: "https://api.context.io/2.0/accounts/4e0928a03edc0c0b021e6070/sources/imap.gmail.com::bruno@widgets.com"
        }
      ], 
      files: [
        {
          size: 423054, 
          type: "image/jpeg", 
          file_name: "Homepage - v1.jpg", 
          main_file_name: "Homepage - v1", 
          file_name_structure: [
            ["Homepage","main"], 
            [" - ","boundary"], 
            ["v1","version"], 
            [".jpg","ext"]
          ], 
          body_section: 2, 
         file_id: "4ed13ed53f757e257d000002", 
          supports_preview: true
        }
      ], 
      message_id: "4fa15ed47e747e202d100006", 
      email_message_id: "<CBOEgs7BW6_1RZb=B3i_R9My-Es39heFtke6qd7bzRYO-o=14_A@mail.gmail.com>", 
      gmail_message_id: "132e1658bcda1ccd", 
      gmail_thread_id: "132e1658bcda1ccd", 
      date_indexed: 1322335957, 
      person_info: {
        tom.thompson@gmail.com: {
          thumbnail: "https://secure.gravatar.com/avatar/c9879ab656ee0bd600b6561a9d56af9a?s=50"
        }, 
        bruno@widgets.com: {
          thumbnail: "https://secure.gravatar.com/avatar/4fc965d14ddff2d5c14fca85d5c0dba0?s=50"
        }
      }
    },
    ...
  ]
}

Get rule-based notifications POSTed to your app. Filter by sender/recipients, attachments, subject, folders and thread.

Example: Create a WebHook to receive notifications when mailbox account_id receives an email from jim@acme.com or dave@acme.com.

POST /2.0/accounts/account_id/webhooks/
filter_from=jim%40acme.com%2Cdave%40acme.com&sync_period=immediate&
callback_url=http%3A%2F%2Fyourapp.com%2Fcb&failure_notif_url=http%3A%2F%2Fyourapp.com%2Fcb%2Ffailure(line break above is only for presentation purposes)
{
  success: true, 
  webhook_id: "4dc4e0f49f724e6219100004", 
  resource_url: "https://api.context.io/2.0/accounts/account_id/webhooks/4dc4e0f49f724e6219100004"
}

Developer tools

From Exploration...

Test calls and inspect the results before writing a single line of code. Check out our tutorial video.

Context.IO Developer Console - API Explorer

...to Code

We provide client libraries for PHP, Ruby, Python and Node.js. You can find them, as well as, example applications on our GitHub account.

{PHP} library for Context.IO {Ruby} library for Context.IO {Python} library for Context.IO {Node.js} library for Context.IO