NAV Navbar
Cio logo white

Getting started

What you need before you start:

Choosing API versions

Context.IO currently has 2 versions of the API: 2.0 and Lite. Below, we’ll help you choose the right one.

2.0 API

The 2.0 version of the API is the oldest version, and slightly more robust than the Lite version. Features 2.0 includes that Lite does not:

When to choose 2.0: If you will need historical data from an email account, or if you need to get a user’s contacts.

Lite

The Lite version of the API is newer and is slightly faster than 2.0 in webhook speed. 2.0 performs an initial sync of an account to perform a historical backscan. This backscan can take time. Lite does not perform this backscan, so messages are available immediately.

When to choose Lite: If your application will not require historical data and you only care about the latest messages coming into the account, or you require faster webhook performance.

2.0 API

Adding accounts

Each user of your application will need to be added to Context.IO as an “account”.

Create an account

You can create an account with no source by only passing in the email param. If you choose this option, you will need to add a source later

HTTP request

POST 2.0/accounts

Required parameters

Parameter Description Type
email The primary email address used to receive emails in this account. string

Optional parameters

Parameter Description Type
first_name First name of the account holder string
last_name Last name of the account holder string
server Name of IP of the IMAP server, eg. imap.gmail.com. Required when creating a source and account in a single call. string
username The username used to authenticate an IMAP connection. On some servers, this is the same thing as the primary email address. Required when creating a source and account in a single call. string
use_ssl Set to 1 if you want SSL encryption to be used when opening connections to the IMAP server. Any other value will be considered as “do not use SSL”. Required when creating a source and account in a single call. integer
port Port number to connect to on the server. For most servers, SSL is 993, and unencrypted (non-SSL) is 143. Required when creating a source and account in a single call. integer
type Currently, the only supported type is IMAP. Required when creating a source and account in a single call. string
sync_all_folders By default, we filter out some folders like ‘Deleted Items’ and 'Drafts’. Set this parameter to 1 to turn off this filtering and show every single folder. integer
expunge_on_deleted_flag By default, we don’t filter out messages flagged as deleted. Set this parameter to 1 to turn on this filtering. integer
password Password for this source. Required when creating a source and account in a single call. Ignored if any of the provider_* parameters are set below. string
provider_refresh_token An OAuth2 refresh token obtained from the IMAP account provider to authenticate this email account. Required if using oauth when creating a source and account in a single call. string
provider_consumer_key The OAuth2 Client ID used to obtain the the refresh token for the above account. Required if using oauth when creating a source and account in a single call. That consumer key and secret must be configured in your Context.IO account, see oauth_providers string
callback_url If specified, we’ll make a POST request to this URL when the initial sync is completed. string (url)
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the source changes. string (url)
{
  "success": true, 
  "id": "55555aaaaa66666bbbbb7777", 
  "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777", 
  "source": {
    "label": "foxmulder::email", 
    "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail"
  }
 }

Add a source

Use this endpoint to add a source to an existing account. An account id is required to add a source to an existing account.

HTTP request

POST 2.0/accounts/:id/sources

Required parameters

Parameter Description Type
email The primary email address used to receive emails in this account string
username The username used to authenticate an IMAP connection. On some servers, this is the same thing as the primary email address. string
server Name of IP of the IMAP server, eg. imap.gmail.com string
use_ssl Set to 1 if you want SSL encryption to be used when opening connections to the IMAP server. Any other value will be considered as “do not use SSL” integer
port Port number to connect to on the server. For most servers, SSL is 993, and unencrypted (non-SSL) is 143. integer
type Currently, the only supported type is IMAP. string

Optional parameters

Parameter Description Type
origin_ip IP address of the end user requesting the account to be created string
expunge_on_deleted_flag By default, we don’t filter out messages flagged as deleted. Set this parameter to 1 to turn on this filtering. integer
sync_all_folders By default, we filter out some folders like 'Deleted Items’ and 'Drafts’. Set this parameter to 1 to turn off this filtering and show every single folder. integer
raw_file_list By default, we filter out files like signature images or those winmail.dat files form the files list. Set this parameter to 1 to turn off this filtering and show every single file attachments. integer
password Password for authentication on the IMAP server. Ignored if any of the provider_* parameters are set below. string
provider_refresh_token An OAuth2 refresh token obtained from the IMAP account provider to authenticate this email account. string
provider_consumer_key The OAuth2 Client ID used to obtain the the refresh token for the above account. That consumer key and secret must be configured in your Context.IO account, see oauth_providers string
callback_url If specified, we’ll make a POST request to this URL when the initial sync is completed. string (url)
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the source changes. string (url)
{
  "success": true, 
  "label": "foxmulder::email", 
  "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail"
}

Connect tokens wizard

Connect tokens are a feature we provide to facilitate account creation. Our connect tokens feature handles:

HTTP request

POST 2.0/connect_tokens

Required parameters

Parameter Description Type
callback_url When the user’s mailbox is connected to your API key, the browser will call this url (GET). This call will have a parameter called contextio_token indicating the connect_token related to this callback. You can then do a get on this connect_token to obtain details about the account and source created through that token and save that account id in your own user data. string (url)

Optional parameters

Parameter Description Type
email The email address of the account to be added. If specified, the first step of the connect UI where users are prompted for their email address, first name and last name is skipped. string
first_name First name of the account holder. string
last_name Last name of the account holder. string
source_callback_url If specified, we’ll make a POST request to this URL when the initial sync is completed. string
source_expunge_on_deleted_flag By default, we don’t filter out messages flagged as deleted. Set this parameter to 1 to turn on this filtering. integer
source_sync_all_folders By default, we filter out some folders like 'Deleted Items’ and 'Drafts’. Set this parameter to 1 to turn off this filtering and show every single folder. integer
source_sync_folders By default, we filter out some folders like 'Deleted Items’ and 'Drafts’. Set this parameter to All,Trash to show the 'Deleted Items’ folder. string
source_raw_file_list By default, we filter out files like signature images or those winmail.dat files form the files list. Set this parameter to 1 to turn off this filtering and show every single file attachments. integer
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the source changes. string (url)
{
  "success": true, 
  "token": "12345abcdef67890", 
  "resource_url": "https://api.context.io/2.0/connect_tokens/12345abcdef67890", 
  "browser_redirect_url": "https://connect.context.io/api/2.0/connect_tokens/12345abcdef67890?developer_key=5555555555555555555555555&branding_url=&branding_width=&branding_height=&branding_tagline="
}

Get connect token details

Getting data about connect token will tell you:

HTTP request

GET 2.0/accounts/connect_tokens/:token

Required parameters

Parameter Description Type
token The unique random token used for the graphical account creation process string

Unused token

{
  "token": "12345abcdef67890", 
  "source_sync_all_folders": false, 
  "source_expunge_on_deleted_flag": false, 
  "source_raw_file_list": true, 
  "created": 1234567890, 
  "used": 0, 
  "callback_url": "https://your-website.com", 
  "account": [ ], 
  "expires": 1234567890, 
  "resource_url": "https://api.context.io/2.0/connect_tokens/12345abcdef67890"
}

Used token

{
    "token": "12345abcdef67890", 
    "email": "foxmulder@email.com", 
    "created": 1234567890, 
    "used": 1234567890, 
    "serverLabel": "foxmulder::email", 
    "callback_url": "https://you-callback.com", 
    "account": {
      "id": "55555aaaaa66666bbbbb7777", 
      "created": 1234567890, 
      "email_addresses": [
        "foxmulder@email.com"
      ], 
      "first_name": "Fox", 
      "last_name": "Mulder", 
      "sources": [
        {
          "server": "imap.email.com", 
          "label": "foxmulder::email", 
          "username": "foxmulder@email.com", 
          "port": 993, 
          "use_ssl": true, 
          "type": "imap", 
          "authentication_type": "oauth2", 
          "status": "OK", 
          "status_message": null, 
          "status_callback_url": null, 
          "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail", 
          "sync_flags": false, 
          "callback_url": null, 
          "sync_all_folders": false, 
          "expunge_on_deleted_flag": false, 
          "raw_file_list": false
        }
      ]
    }, 
    "expires": false, 
    "resource_url": "https://api.context.io/2.0/connect_tokens/12345abcdef67890"
  }

List connect tokens

List connect tokens for an account

Use this call to list all connect tokens associated with an account (used or unused).

HTTP request

GET 2.0/accounts/:id/connect_tokens/

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer

List connect tokens for a source

Use this call to list all connect tokens associated with a source (used or unused).

HTTP request

GET 2.0/accounts/:id/sources/:label

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer
label The label property of the source instance. string
{
    "token": "12345abcdef67890", 
    "email": "foxmulder@email.com", 
    "created": 1234567890, 
    "used": 1234567890, 
    "serverLabel": "foxmulder::email", 
    "callback_url": "https://you-callback.com", 
    "account": {
      "id": "55555aaaaa66666bbbbb7777", 
      "created": 1234567890, 
      "email_addresses": [
        "foxmulder@email.com"
      ], 
      "first_name": "Fox", 
      "last_name": "Mulder", 
      "sources": [
        {
          "server": "imap.email.com", 
          "label": "foxmulder::email", 
          "username": "foxmulder@email.com", 
          "port": 993, 
          "use_ssl": true, 
          "type": "imap", 
          "authentication_type": "oauth2", 
          "status": "OK", 
          "status_message": null, 
          "status_callback_url": null, 
          "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail", 
          "sync_flags": false, 
          "callback_url": null, 
          "sync_all_folders": false, 
          "expunge_on_deleted_flag": false, 
          "raw_file_list": false
        }
      ]
    }, 
    "expires": false, 
    "resource_url": "https://api.context.io/2.0/connect_tokens/12345abcdef67890"
  }

Get account details

Getting details at the account level will give you:

HTTP request

GET 2.0/accounts/:id

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer
{
  "id": "55555aaaaa66666bbbbb7777", 
  "created": 1234567890, 
  "email_addresses": [
    "foxmulder@email.com"
  ], 
  "first_name": "Fox", 
  "last_name": "Mulder", 
  "nb_messages": 100, 
  "sources": [
    {
      "server": "imap.email.com", 
      "label": "foxmulder::email", 
      "username": "foxmulder@email.com", 
      "port": 993, 
      "use_ssl": true, 
      "type": "imap", 
      "authentication_type": "oauth2", 
      "status": "OK", 
      "status_message": null, 
      "status_callback_url": "https://your-callback.com", 
      "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail", 
      "sync_flags": false, 
      "callback_url": null, 
      "sync_all_folders": false, 
      "expunge_on_deleted_flag": false, 
      "raw_file_list": true
    }
  ]
}

List all sources

If the account has more than once source, this endpoint will list all sources associated with the account. Optional parameters will allow you to filter by source status.

HTTP request

GET 2.0/accounts/:id/sources

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer

Optional parameters

Parameter Description Type
status Only return sources whose status is of a specific value. Possible statuses are: INVALID_CREDENTIALS, CONNECTION_IMPOSSIBLE, OK, TEMP_DISABLED and DISABLED string
status_ok Set to 0 to get sources that are not working correctly. Set to 1 to get those that are. integer

Getting details of a specific source

The name of a source in Context.IO is called a “label”. The label will be included in the response when you get account or source details and looks something like “"email::provider”“.

You can use the integer "0” as shorthand for the first label on the account (subsequent labels don’t have a shorthand, a full label will need to be used).

HTTP request

GET 2.0/accounts/:id/sources/:label

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer
label The label property of the source instance. string
{
    "server": "imap.email.com", 
    "label": "foxmulder::email", 
    "username": "foxmulder@email.com", 
    "port": 993, 
    "use_ssl": true, 
    "type": "imap", 
    "authentication_type": "oauth2", 
    "status": "OK", 
    "status_message": null, 
    "status_callback_url": "https://your-callback.com", 
    "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail", 
    "sync_flags": false, 
    "callback_url": null, 
    "sync_all_folders": false, 
    "expunge_on_deleted_flag": false, 
    "raw_file_list": true
}

Listing messages

List all messages in the account (including all sources associated with the account). This call hits our cache of metadata for the account, so this call should be faster than hitting IMAP

If you are not requesting message bodies or headers, this call hits our cache and should be quite fast. If you are requesting bodies or headers, this call goes to IMAP, so expect a performance hit.

HTTP request

GET 2.0/accounts/:id/messages

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer

Optional parameters

Parameter Description Type
subject Get messages whose subject matches this search string. To use regular expressions instead of simple string matching, make sure the string starts and ends with /. string
email Email address or top level domain of the contact for whom you want the latest messages exchanged with. By “exchanged with contact X” we mean any email received from contact X, sent to contact X or sent by anyone to both contact X and the source owner. string
to Email address of a contact messages have been sent to. string
from Email address of a contact messages have been received from. string
cc Email address of a contact CC'ed on the messages. string
bcc Email address of a contact BCC'ed on the messages. string
folder Filter messages by the folder (or Gmail label). This parameter can be the complete folder name with the appropriate hierarchy delimiter for the mail server being queried (eg. Inbox/My folder) or the “symbolic name” of the folder (eg. \Starred). The symbolic name refers to attributes used to refer to special use folders in a language-independent way. See RFC-6154. string
source Filter messages by the account source label. string
file_name Search for files based on their name. You can filter names using typical shell wildcards such as *, ? and [] or regular expressions by enclosing the search expression in a leading / and trailing /. For example, *.pdf would give you all PDF files while /.jpe?g$/ would return all files whose name ends with .jpg or .jpeg string
file_size_min Search for files based on their size (in bytes). integer
file_size_max Search for files based on their size (in bytes). integer
date_before Only include messages before a given timestamp. The value this filter is applied to is the Date: header of the message which refers to the time the message is sent from the origin. integer (Unix timestamp)
date_after Only include messages after a given timestamp. The value this filter is applied to is the Date: header of the message which refers to the time the message is sent from the origin. integer (Unix timestamp)
indexed_before Only include messages indexed before a given timestamp. This is not the same as the date of the email, it is the time Context.IO indexed this message. integer Unix timestamp)
indexed_after Only include messages indexed after a given timestamp. This is not the same as the date of the email, it is the time Context.IO indexed this message. integer (Unix timestamp)
include_thread_size Set to 1 to include thread size in the result. integer
include_body Set to 1 to include message bodies in the result. Since message bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
include_headers Can be set to 0 (default), 1 or raw. If set to 1, complete message headers, parsed into an array, are included in the results. If set to raw, the headers are also included but as a raw unparsed string. Since full original headers bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter. mixed
include_flags Set to 1 to include IMAP flags of messages in the result. Since message flags must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
body_type Used when include_body is set to get only body parts of a given MIME-type (for example text/html) string
include_source Set to 1 to include message sources in the result. Since message sources must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
sort_order The sort order of the returned results. Possible values are asc and desc string
limit The maximum number of results to return. The maximum limit is 100. The default if no limit is provided is 25. integer
offset Start the list at this offset (zero-based). integer

Listing messages from a specific folder

To get messages from a specific folder, you can perform the GET call specified above and pass in a folder parameter (“GET 2.0/accounts/:id/messages?folder=FOLDER”).

Alterntively, you can also perform the following call by source. This call bypases our cache of the account, so expect a performance hit.

HTTP request

GET 2.0/accounts/:id/sources/:label/folders/:folder/messages

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
label The label property of the source instance. You can use 0 as an alias for the first source of an account. integer
folder The full folder path using / as the path hierarchy delimiter. string

Optional parameters

Parameter Description Type
include_thread_size Set to 1 to include thread size in the result. integer
include_body Set to 1 to include message bodies in the result. Since message bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
body_type Used when include_body is set to get only body parts of a given MIME-type (for example text/html) string
include_headers Can be set to 0 (default), 1 or raw. If set to 1, complete message headers, parsed into an array, are included in the results. If set to raw, the headers are also included but as a raw unparsed string. Since full original headers bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter. mixed
include_flags Set to 1 to include IMAP flags for this message in the result. Since message flags must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
flag_seen Set to 1 to restrict list to messages having the “\Seen” flag set, set to 0 to have the messages with that flag unset (ie. list unread messages in the folder). integer
limit The maximum number of results to return. The maximum limit is 100. The default if no limit is provided is 25. integer
offset Start the list at this offset (zero-based). integer

Getting an individual message

Get an individual message based on a “message_id”. You can use either a “message_id” or “email_message_id”.

If you are not requesting the message body or headers, this call will hit our cache and should be quite fast. If you are requesting message body, headers, or flags, this call will go to IMAP.

HTTP request

GET 2.0/accounts/:id/messages/:message_id

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer
message_id Unique id of a message. This can be the “message_id” or “email_message_id” property of the message. The “gmail_message_id” (prefixed with gm-) can also be used. integer

Optional parameters

Parameter Description Type
include_thread_size Set to 1 to include thread size in the result. integer
include_body Set to 1 to include the message body in the result. Since the body must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
include_headers Can be set to 0 (default), 1 or raw. If set to 1, complete message headers, parsed into an array, are included in the results. If set to raw, the headers are also included but as a raw unparsed string. Since full original headers bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
include_flags Set to 1 to include IMAP flags for this message in the result. Since message flags must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
body_type Used when include_body is set to get only body parts of a given MIME-type (for example text/html) string
include_source Set to 1 to include message sources in the result. Since message sources must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
  {
    "date": 1234567890, 
    "folders": [
      "INBOX", 
      "\\Inbox"
    ], 
    "addresses": {
      "from": {
        "email": "danascully@email.com", 
        "name": "Dana Scully"
      }, 
      "to": [
        {
          "email": "foxmulder@email.com"
        }
      ]
    }, 
    "sources": [
      {
        "label": "foxmulder::email", 
        "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail"
      }
    ], 
    "subject": "I want to believe", 
    "message_id": "55555ccccc22222ddddd3333", 
    "email_message_id": "<12345_abcde@email.com>", 
    "gmail_message_id": "1234567abcdef890", 
    "gmail_thread_id": "1234567abcdef891", 
    "date_received": 1234567890, 
    "date_indexed": 1234567890,
    "body": [
      {
        "type": "text/plain", 
        "charset": "utf-8", 
        "delsp": "yes", 
        "format": "flowed", 
        "content": "some email content ...", 
        "body_section": "1"
      }
    ], 
    "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/messages/55555ccccc22222ddddd3333"
  }

Copying or moving a message

This call allows you to copy or move a message between folders. If there are more than one source on the account, you can use this call to copy/move the message between these sources. In this case, the “dst_label” parameter must identify the source you want to message to be copied/moved to.

HTTP request

POST 2.0/accounts/:id/messages/:message_id

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer
message_id Unique id of a message. This can be the “message_id” or “email_message_id” property of the message. The “gmail_message_id” (prefixed with gm-) can also be used. integer
{
  "success": true
}

Deleting a message

Delete a message from an email mailbox. The exact behavior varies depending on the type of mailbox provider.

For standard IMAP accounts

The “DELETE” method will delete messages from the source email server. In IMAP-speak, it will set the “\Deleted” flag on the message and then call the “EXPUNGE” command.

Once this is done, the message is gone forever, there’s no way to bring it back.

For Gmail and Google Apps accounts

For Gmail and Google Apps mailboxes, setting the “\Deleted” flag and calling the “EXPUNGE” command is equivalent to removing a “label” and results in that message still showing up in the “All Mail” folder and other labels also assigned to the message.

So, if you call the “DELETE” method on a message we assume it’s because you wanted that message deleted. Therefore, what actually happens for Gmail or Google Apps messages is we move it to the “[Gmail]/Trash” folder.

HTTP request

DELETE 2.0/accounts/:id/messages/:message_id

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer
message_id Unique id of a message. This can be the “message_id” or “email_message_id” property of the message. The “gmail_message_id” (prefixed with gm-) can also be used. integer
{
  "success": true
}

Listing folders

List folders for a given source (email address).

HTTP request

GET 2.0/accounts/:id/sources/:label/folders

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer
source The label property of the source instance. You can use 0 as an alias for the first source of an account. string

Optional parameters

Parameter Description Type
include_extended_counts Set to 1 to include extended counts in the result (for now, the only extended count supported is number of unseen messages). Since counts must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
no_cache Set to 1 to fetch the folder list directly from the IMAP server. Since data must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer

Getting an individual folder

Get information about a given folder such as number of messages, number of unseen messages, and other attributes.

HTTP request

GET 2.0/accounts/:id/sources/:label/folders/:folder

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key. integer
source The label property of the source instance. You can use 0 as an alias for the first source of an account. string
folder The full folder path using / as the path hierarchy delimiter. string

Optional parameters

Parameter Description Type
delim If / isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delim parameter to tell us what you’re using. string
include_extended_counts Set to 1 to include extended counts in the result (for now, the only extended count supported is number of unseen messages). Since counts must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
{
  "name": "INBOX", 
  "symbolic_name": "\\Inbox", 
  "xlist_name": "\\Inbox", 
  "attributes": {
    "HasChildren": false, 
    "HasNoChildren": true, 
    "Noinferiors": false, 
    "Marked": false, 
    "Noselect": false
  }, 
  "delim": "/", 
  "nb_messages": 100, 
  "nb_unseen_messages": 10, 
  "delimiter": "/", 
  "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail/folders/INBOX"
}

Webhooks

If you would like to receive notifications when a new message is received in a mailbox, you should use webhooks. Learn more about webhooks here.

A webhook is an HTTP callback that is triggered based on an event (receiving a message, sending a message, etc). If you setup a webhook, we will peform a callback to a callback URL on your domain via HTTP POST request.

You can setup webhooks at the user level, or at the application level.

User level webhooks

Webhooks set at the user level are applicable only to the user on which the webhook is set. User level webhooks should be used for cases when you will be monitoring things that are very specific to each individual user.

Create a user level webhook

HTTP Request

POST 2.0/accounts/:id/webhooks

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
callback_url A valid URL Context.IO calls when a matching message is found. The callback URL is called with an HTTP POST with message information in request body, see receiving webhook callbacks. string
failure_notif_url (DEPRECATED) A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can’t re-establish it.
string

Optional parameters

Parameter Description Type
filter_to Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_cc Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses. string
filter_subject Check for new messages with a subject matching a given string or regular expresion string
filter_thread Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id of an existing message currently in the thread. string
filter_file_name Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the files list call. string
filter_folder_added Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_folder_removed Check for messages removed from a given folder. On Gmail, this is equivalent to having a label removed from a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_to_domain Check for new messages sent to a given domain. Also accepts a comma delimited list of domains. string
filter_from_domain Check for new messages sent from a given domain. Also accepts a comma delimited list of domains. string
include_body Set to 1 or raw to include message bodies in the result. integer
body_type Required to be set when “include_body” is set to get only body parts of a given MIME-type. Acceptable values are “text/html” or “text/plain”. string
include_header Set to 1 or raw to include message headers in the result. integer
receive_all_changes By default, we only send a webhook notification on the first event of a message (i.e. when a message is received or sent). Subsequent changes of a specific message do not trigger a webhook (i.e. if a message changes folders). When this parameter is set to 1, we will send all events related to a message. integer
receive_drafts Set to 1, you will receive messages that are flagged as “\Drafts” in Gmail integer

List all webhooks set on a specific user

HTTP Request

GET 2.0/accounts/:id/webhooks

List all webhooks set on a specific user.

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer

Get information about a specific user level webhook

Get information about a single user level webhook, such whether it is active and what filters are set on the webhook.

HTTP Request

GET 2.0/accounts/:id/webhooks/:webhook_id

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
webhook_id Unique id of a user level webhook integer

Edit an existing user level webhook

Edit an existing user level webhook. Please note changes to an existing webhook are not appended but overwritten.

HTTP Request

POST 2.0/accounts/:id/webhooks/:webhook_id

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
webhook_id id Unique id of a user level webhook

Optional parameters

Parameter Description Type
callback_url A valid URL Context.IO calls when a matching message is found. The callback URL is called with an HTTP POST with message information in request body, see receiving webhook callbacks. string
failure_notif_url (DEPRECATED) A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can’t re-establish it.
string
active By default, webhooks are set to active when first created. Set to 0 to temporarily stop receiving callbacks for this webhook. Set to 1 again to resume. integer
filter_to Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_cc Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses. string
filter_subject Check for new messages with a subject matching a given string or regular expresion string
filter_thread Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id of an existing message currently in the thread. string
filter_file_name Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the files list call. string
filter_folder_added Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_folder_removed Check for messages removed from a given folder. On Gmail, this is equivalent to having a label removed from a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_to_domain Check for new messages sent to a given domain. Also accepts a comma delimited list of domains. string
filter_from_domain Check for new messages sent from a given domain. Also accepts a comma delimited list of domains. string
include_body Set to 1 or raw to include message bodies in the result. integer
body_type Required to be set when “include_body” is set to get only body parts of a given MIME-type. Acceptable values are “text/html” or “text/plain”. string
include_header Set to 1 or raw to include message headers in the result. integer
receive_all_changes By default, we only send a webhook notification on the first event of a message (i.e. when a message is received or sent). Subsequent changes of a specific message do not trigger a webhook (i.e. if a message changes folders). When this parameter is set to 1, we will send all events related to a message. integer
receive_drafts Set to 1, you will receive messages that are flagged as “\Drafts” in Gmail integer

Delete a specific user level webhook

HTTP Request

DELETE 2.0/accounts/:id/webhooks/:webhook_id

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
webhook_id id Unique id of a user level webhook

Application level webhooks

Webhooks set at the application level apply to all users in your userbase. Application level webhooks are encouraged over user level webhooks when you:

Application level webhooks encourage a more DRY approach to using the Context.IO API.

Create an application level webhook

HTTP Request

POST 2.0/webhooks

Required parameters

Parameter Description Type
callback_url A valid URL Context.IO calls when a matching message is found. The callback URL is called with an HTTP POST with message information in request body, see receiving webhook callbacks. string
failure_notif_url (DEPRECATED) A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can’t re-establish it.
string

Optional parameters

Parameter Description Type
active By default, webhooks are set to active when first created. Set to 0 to temporarily stop receiving callbacks for this webhook. Set to 1 again to resume. integer
filter_to Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_cc Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses. string
filter_subject Check for new messages with a subject matching a given string or regular expresion string
filter_thread Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id of an existing message currently in the thread. string
filter_file_name Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the files list call. string
filter_folder_added Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_folder_removed Check for messages removed from a given folder. On Gmail, this is equivalent to having a label removed from a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_to_domain Check for new messages sent to a given domain. Also accepts a comma delimited list of domains. string
filter_from_domain Check for new messages sent from a given domain. Also accepts a comma delimited list of domains. string
include_body Set to 1 or raw to include message bodies in the result. integer
body_type Required to be set when “include_body” is set to get only body parts of a given MIME-type. Acceptable values are “text/html” or “text/plain”. string
include_header Set to 1 or raw to include message headers in the result. integer
receive_all_changes By default, we only send a webhook notification on the first event of a message (i.e. when a message is received or sent). Subsequent changes of a specific message do not trigger a webhook (i.e. if a message changes folders). When this parameter is set to 1, we will send all events related to a message. integer
receive_drafts Set to 1, you will receive messages that are flagged as “\Drafts” in Gmail integer
receive_historical Set to 1, we will perform a backscan of an account when a new account is added and send messages from new to old to your callback URL. integer

List all application level webhooks

List all application level webhooks.

HTTP Request

GET 2.0/webhooks

Get information about a specific application level webhook

Get information about a single application level webhook, such whether it is active and what filters are set on the webhook.

Required parameters

Parameter Description Type
webhook_id Unique id of an application level webhook integer

Edit a specific application level webhook

Edit an existing webhook. Please note changes to an existing webhook are not appended but overwritten.

HTTP Request

POST 2.0/webhooks/:webhook_id

Required parameters

Parameter Description Type
webhook_id Unique id of an application level webhook integer

Optional parameters

Parameter Description Type
active By default, webhooks are set to active when first created. Set to 0 to temporarily stop receiving callbacks for this webhook. Set to 1 again to resume. integer
filter_to Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_cc Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses. string
filter_subject Check for new messages with a subject matching a given string or regular expresion. string
filter_thread Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id of an existing message currently in the thread. string
filter_file_name Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the files list call. string
filter_folder_added Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_folder_removed Check for messages removed from a given folder. On Gmail, this is equivalent to having a label removed from a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_to_domain Check for new messages sent to a given domain. Also accepts a comma delimited list of domains. string
filter_from_domain Check for new messages sent from a given domain. Also accepts a comma delimited list of domains. string
include_body Set to 1 or raw to include message bodies in the result. integer
body_type Required to be set when “include_body” is set to get only body parts of a given MIME-type. Acceptable values are “text/html” or “text/plain”. string
include_header Set to 1 or raw to include message headers in the result. integer
receive_all_changes By default, we only send a webhook notification on the first event of a message (i.e. when a message is received or sent). Subsequent changes of a specific message do not trigger a webhook (i.e. if a message changes folders). When this parameter is set to 1, we will send all events related to a message. integer
receive_drafts Set to 1, you will receive messages that are flagged as “\Drafts” in Gmail. integer
receive_historical Set to 1, we will perform a backscan of an account when a new account is added and send messages from new to old to your callback URL. integer

Delete a specific application level webhook

Delete an existing application level webhook.

HTTP Request

DELETE 2.0/webhooks/:webhook_id

Required parameters

Parameter Description Type
webhook_id Unique id of an application level webhook integer

Webhook created response

{
  "success": true, 
  "webhook_id": "55555ddddd66666eeeee7777", 
  "resource_url": "https://api.context.io/2.0/..."
}

Webhook details response

  {
    "callback_url": "https://your-callback.com", 
    "failure_notif_url": "https://your-callback.com", 
    "active": true, 
    "webhook_id": "55555ddddd66666eeeee7777", 
    "resource_url": "https://api.context.io/2.0/..."
  }

Edit webhook response

{
  "success": true, 
  "resource_url": "https://api.context.io/2.0/..."
}

Delete webhook response

{
  "success": true 
}

Receiving webhook callbacks

When an event matching the filters set for your webhook occurs in the mailbox, we do an HTTP POST request to your callback_url.

When you receive the POST request from our servers, it is important to respond to it with a 200 before doing any additional processing.

Authenticating requests to your callback URL

You can validate that a request to your callback URL is a valid request from Context.IO using the combination of the timestamp, token and signature properties in the body. The signature is the HMAC-SHA256 hash of the string formed by concatenating the timestamp and token using your Context.IO OAuth secret as the hashing key.

Issues with Apache and mod_security

The mod_security module for Apache decided application/json is an exotic Content-type for the body of a POST request and rejects them by default, typically with a 406 status code. To avoid having Apache reject WebHook callbacks, you need to either change default mod_security configs or disable it for your domain. You can learn more about this here.

Sample webhook payload

{"account_id":"55555aaaaa66666bbbbb7777","webhook_id":"55555ddddd66666eeeee7777","timestamp":1234567890,"message_data":{"message_id":"55555444446666677778888","email_message_id":"\u003c12345_abcde@email.com\u003e","addresses":{"from":{"email":"danascully@email.com","name":"Dana Scully"},"to":[{"email":"foxmulder@email.com"}],"return_path":[{"email":"danascully@email.com"}]},"person_info":{"danascully@email.com":{"thumbnail":"https://secure.gravatar.com/avatar/contact.png"},"danascully@email.com":{"thumbnail":"https://secure.gravatar.com/avatar/contact.png"}},"date_received":1234567890,"subject":"I want to believe","folders":["INBOX","\\Inbox"],"bodies":[{"type":"text/plain","charset":"utf-8","body_section":"1"},{"type":"text/html","charset":"utf-8","body_section":"2"}],"email_accounts":[{"label":"foxmulder::email","resource_url":"https://api.context.io/2.0/users/5931cebae5c6bf22ea47ad53/email_accounts/scullyd35%3A%3Agmail","folder":"[Gmail]/All Mail","uid":103}],"flags":{"flagged":false,"answered":false,"draft":false,"seen":false},"date":1496436749,"references":[],"files":[],"sources":[{"label":"scullyd35::gmail","resource_url":"https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail","folder":"Inbox","uid":101}]},"token":"xxxxx","signature":"xxxxx"}

Contacts

There are several ways you can interact with a user’s contacts.

List all contacts

HTTP Request

GET 2.0/accounts/:id/contacts

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer

Optional parameters

Parameter Description Type
search String identifying the name or the email address of the contact(s) you are looking for. string
active_before Only include contacts included in at least one email dated before a given time. This parameter should be a standard Unix timestamp. integer (Unix timestamp)
active_after Only include contacts included in at least one email dated after a given time. This parameter should be a standard Unix timestamp. integer (Unix timestamp)
sort_by The field by which to sort the returned results. Possible values are “email”, “count”, “received_count” and “sent_count”. string
sort_order The sort order of the returned results. Possible values are “asc” and “desc”. string
limit The maximum number of results to return. The maximum per call is 100. integer
offset Start the list at this offset (zero-based). integer

Get information about a specific contact

Get information about a given contact such as when a message was last sent or last received, as well as how many messages have been sent to this contact, or received from this contact.

HTTP Request

GET 2.0/accounts/:id/contacts/:email

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
email Email address of a contact string

List files shared with a specific contact(s)

HTTP Request

GET 2.0/accounts/:id/contacts/:email/files

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
email Email address of a contact string

Optional parameters

Parameter Description Type
limit The maximum number of results to return. The maximum per call is 100. integer
offset Start the list at this offset (zero-based). integer

List messages exchanged between an account and a specific contact

HTTP Request

GET 2.0/accounts/:id/contacts/:email/messages

Get a list of email messages exchanged with one or more email addresses. This includes messages sent by a contact, received from a contact, or where both the contact and mailbox owner are included in the list of recipients.

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
email Email address of a contact string

Optional parameters

Parameter Description Type
limit The maximum number of results to return. The maximum per call is 100. integer
offset Start the list at this offset (zero-based). integer

List threads that include a specific contact

List threads where a specific contact(s) is present in the recipient list.

HTTP Request

GET 2.0/accounts/:id/contacts/:email/threads

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
email Email address of a contact string

Optional parameters

Parameter Description Type
limit The maximum number of results to return. The maximum per call is 100. integer
offset Start the list at this offset (zero-based). integer

Contact list response

{
  "query": {
    "limit": 25, 
    "offset": 0, 
    "active_after": null, 
    "active_before": null, 
    "search": null
  }, 
  "matches": [
    {
      "email": "danascully@email.com", 
      "count": 1, 
      "sent_count": 1, 
      "received_count": 1, 
      "sent_from_account_count": 1, 
      "name": "Dana Scully", 
      "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/contacts/danascully%40email.com", 
      "last_sent": 1234567890, 
      "last_received": 1234567890
    }

Single contact response

{
  "count": 1, 
  "sent_count": 1, 
  "received_count": 1, 
  "sent_from_account_count": 1, 
  "name": "Willow Rosenberg", 
  "last_received": 1234567890, 
  "last_sent": 1234567890, 
  "emails": [
    "danascully@email.com"
  ]
}

Files from contact response

Same as files response

Messages from contact response

Same as messages response

Threads from contact response

Same as threads response

Working with files or attachments

Get information about files and download content.

List all files in an account

Get a list of files in an account.

HTTP Request

GET 2.0/accounts/:id/files

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer

Optional parameters

Parameter Description Type
file_name Search for files based on their name. You can filter names using typical shell wildcards such as “”, “?” and “[]” or regular expressions by enclosing the search expression in a leading “/” and trailing “/”. For example, “.pdf” would give you all PDF files while “/.jpe?g$/” would return all files whose name ends with “.jpg” or “.jpeg” string
file_size_min Search for files based on their size (in bytes). integer
file_size_max Search for files based on their size (in bytes). integer
email Email address of the contact for whom you want the latest files in which this email address was listed as a recipient. string
to Email address of a contact files have been sent to. string
from Email address of a contact files have been received from. string
cc Email address of a contact CC'ed on the messages. string
bcc Email address of a contact BCC'ed on the messages. string
date_before Only include files attached to messages sent before a given timestamp. The value this filter is applied to is the “Date:” header of the message which refers to the time the message is sent from the origin. integer (Unix timestamp)
date_after Only include files attached to messages sent after a given timestamp. The value this filter is applied to is the “Date:” header of the message which refers to the time the message is sent from the origin. integer (Unix timestamp)
indexed_before Only include files attached to messages indexed before a given timestamp. This is not the same as the date of the email, it is the time Context.IO indexed this message. integer (Unix timestamp)
indexed_after Only include files attached to messages indexed after a given timestamp. This is not the same as the date of the email, it is the time Context.IO indexed this message. integer (Unix timestamp)
source Filter messages by the account source label. string
sort_order The sort order of the returned results. Possible values are “asc” and “desc”. string
limit The maximum number of results to return. The maximum per call is 100. integer
offset Start the list at this offset (zero-based). integer

Get details about a specific file

HTTP Request

GET 2.0/accounts/:id/files/:file_id

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
file_id Unique id of a file integer

Download a file’s contents

There are a couple ways you can download the file itself from the API.

If you make the call below without the parameter “as_link” set to “1”, the response you get from the API will be the file itself. Simply save the file on your end using the name and extention listed in when you make a call to get data about a specific file (i.e. “GET 2.0/accounts/:id/files/:file_id”).

If you set “as_link” to “1”, you will receive a raw response with a link to AWS where you or the end-user can download the file. This is a temporary link only valid for a 2 minute period.

Since we do not keep full copies of attachments on our servers, the file has to be retrieved from the IMAP server before a response is returned. This is true whether you’re asking for a tokenized public link to the content or requesting the content itself. If the IMAP server is unreachable at the time the call is made, this call will return an error.

HTTP Request

GET 2.0/accounts/:id/files/:file_id/content

Required parameters

Parameter Description Type
id Unique id of an account accessible through your API key integer
file_id Unique id of a file integer

Optional parameters

Parameter Description Type
as_link Set to 1, get an AWS link you can use to download the file integer

Files response

{
    "size": 9000, 
    "type": "image/jpeg", 
    "subject": "I want to believe", 
    "date": 1234567890, 
    "addresses": {
      "from": {
        "email": "danascully@email.com", 
        "name": "Dana Scully"
      }, 
      "to": [
        {
          "email": "foxmulder@email.com"
        }
      ]
    }, 
    "file_name": "proof", 
    "body_section": "2", 
    "file_id": "55555fffff77777ggggg8888", 
    "is_tnef_part": false, 
    "supports_preview": false, 
    "message_id": "55555444446666677778888", 
    "date_indexed": 1234567890, 
    "date_received": 1234567890, 
    "email_message_id": "<12345_abcde@email.com>", 
    "gmail_message_id": "1234567abcdef890", 
    "gmail_thread_id": "1234567abcdef891", 
    "file_name_structure": "hidden", 
    "is_embedded": false, 
    "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/files/55555fffff77777ggggg8888"
  }

File as link response

https://s3.amazonaws.com/link/to/file

Reconnecting sources

There will be times when a source gets disconnected from Context.IO. Causes for disconnection are always due to a change in credentials on the end-user’s side. Causes for disconnetion include:

Source status

When a change in credentials happens and we lose our ability to connect to a source, we mark the source as “DISABLED”.

When you perform a request to the API, we include the user’s source status in the response headers as “X-Contextio-Source-Status”.

A source in “OK” status will display as follows in the headers we return:

X-Contextio-Source-Status: https://api.context.io/2.0/accounts/:id/sources/:source OK

A source in “DISABLED” status will display as follows in the headers we return:

X-Contextio-Source-Status: https://api.context.io/2.0/accounts/:id/sources/:source DISABLED

Manually checking source status

You can 'manually’ check the status of a specific source via the following request:

GET 2.0/accounts/:id/sources/:label

You can also check the status of all sources associated to an account via this request:

GET 2.0/accounts/:id

The API will return “status” and “status_message” values as part of the response, which will provide details on the status of a source.

{
  "server": "imap.email.com", 
  "label": "foxmulder::email", 
  "username": "foxmulder@email.com", 
  "port": 993, 
  "use_ssl": true, 
  "type": "imap", 
  "authentication_type": "oauth2", 
  "status": "OK", 
  "status_message": null, 
  "status_callback_url": "https://your-callback.com", 
  "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail", 
  "sync_flags": false, 
  "callback_url": null, 
  "sync_all_folders": false, 
  "expunge_on_deleted_flag": false, 
  "raw_file_list": true
}

Status callback push notification

Checking for the status of a source manually is not ideal, as such, we provide a way for developers to receive notifications when a source goes into “DISABLED” status by setting a “status_callback_url”. This “status_callback_url” is an endpoint on the developer’s side where we will perform a callback when a source goes into “DISABLED” status.

You can:

Setting a status_callback_url_ at the source level

You can include a “status_callback_url” param when you create a source via a “POST 2.0/accounts/:id/sources/:label” request, or you can add it after source creation on the same endpoint by passing in a “status_callback_url” value.

HTTP Request

POST 2.0/accounts/:id/sources/:label

Optional parameters

Parameter Description Type
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the source changes. string (url)
Setting a status_callback_url_ at the application level

You can set a “global” “status_callback_url” at the application level, where we will send all status postbacks to, if you prefer to receive all callbacks on the same endpoint.

HTTP Request

POST 2.0/accounts/:id/sources/:label

Optional parameters

Parameter Description Type
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the source changes. string (url)

status_callback_url payload for DISABLED accounts

{"account_id":"55555aaaaa66666bbbbb7777","user_id":"55555aaaaa66666bbbbb7777","server_label":"foxmulder::email","email_account":"foxmulder::email","timestamp":1234567890,"failure":"permanent"}

status_callback_url payload for cleared accounts

{"account_id":"55555aaaaa66666bbbbb7777","user_id":"55555aaaaa66666bbbbb7777","server_label":"foxmulder::email","email_account":"foxmulder::email","timestamp":1234567890,"failure":"cleared"}

Discovering IMAP settings

If you prefer to handle your own authentication and add accounts or sources manually, you may want to check for IMAP configuration settings to add users. The Discovery endpoint returns known IMAP configuration settings given an email address.

This endpoint checks IMAP server information in the following 3 places:

The information from the Discovery endpoint should not be treated as a single source of truth, as these settings can be changed by the provider at any time without notice.

HTTP Request

GET 2.0/discovery

Required parameters

Parameter Description Type
source_type The type of source you want to discover settings for. Right now, the only supported source type is “IMAP” string
email An email address you want to discover IMAP settings for. Make sure source_type is set to “IMAP”. string
{
  "email": "danascully@email.com", 
  "found": true, 
  "resource_url": "https://api.context.io/lite/discovery", 
  "type": "gmail", 
  "imap": {
    "server": "imap.email.com", 
    "username": "danascully@email.com", 
    "port": 993, 
    "use_ssl": true, 
    "oauth": true
  }, 
  "documentation": [ ]
}

Custom oauth providers

You can associate your own oauth provider keys with your Context.IO API key, in fact, we recommend all developers use their own oauth provider keys to authenticate users with.

Context.IO supports oauth for the following providers:

Oauth provider set-up

Google Create a new application via the Google Developer Console if you have not already. When handling your own oauth, you must make sure you ask for the right scope. To connect to the IMAP servers the scope must be full access “https://mail.google.com/”. See the Google documentation here. Also it is important to set the redirect URL. The redirect url you should use is “https://api.context.io/connect/oauth2callback”.

Microsoft Create a new applicaiton via the Microsoft Application Portal if you have not already. Click on “API Settings” and under redirect URLs, add the following URL, “https://{CIO OAuth Key}.api.context.io/connect/mslivecallback”, then click “Save”.

Get a list of oauth providers

List all oauth providers linked to your Context.IO API key.

HTTP Request

GET 2.0/oauth_providers

Add an oauth provider

HTTP Request

POST 2.0/oauth_providers

Required parameters

Parameter Description Type
type Identification of the OAuth2 provider. Possible values are GMAIL_OAUTH2 and MSLIVECONNECT. string
provider_consumer_key The OAuth2 Client ID string
provider_consumer_secret The OAuth2 Client Secret string

Get information about an oauth provider

“GET 2.0/oauth_providers/:key”

Required parameters

Parameter Description Type
key The consumer key for this external OAuth provider string

Delete an oauth provider

“DELETE 2.0/oauth_providers/:key”

Required parameters

Parameter Description Type
key The consumer key for this external OAuth provider string
  {
    "provider_consumer_key": "xxxxxxxxx.apps.googleusercontent.com", 
    "provider_consumer_secret": "xxx[...]xxx", 
    "type": "GMAIL_OAUTH2", 
    "resource_url": "https://api.context.io/2.0/oauth_providers/xxxxxxxxx.apps.googleusercontent.com"
  }

Lite API

Adding users

Each user of your application will need to be added to Context.IO as a “user”.

Creating a user

When you create a user you must also provide valid credentials for their email account.

HTTP request

POST lite/users

Required parameters

Parameter Description Type
email The primary email address used to receive emails in this user. string
server Name of IP of the IMAP server, eg. imap.email.com. Required when creating a email account and user in a single call. string
username The username used to authenticate an IMAP connection. On some servers, this is the same thing as the primary email address. string
use_ssl Set to 1 if you want SSL encryption to be used when opening connections to the IMAP server. Any other value will be considered as “do not use SSL”. Required when creating a email account and user in a single call. integer
port Port number to connect to on the server. For most servers, SSL is 993, and unencrypted (non-SSL) is 143. Required when creating a email account and user in a single call. integer
type Currently, the only supported type is IMAP. Required when creating a email account and user in a single call. string
password Password for this email account. Required when creating a email account and user in a single call. Ignored if any of the provider_* parameters are set below. string
provider_refresh_token An OAuth2 refresh token obtained from the IMAP user provider to authenticate this email user. Required if using oauth when creating a email account and user in a single call. string
provider_consumer_key The OAuth2 Client ID used to obtain the the refresh token for the above user. Required if using oauth when creating a email account and user in a single call. That consumer key and secret must be configured in your Context.IO user, see oauth_providers string

Optional parameters

Parameter Description Type
migrate_account_id Existing 2.0 account_id you want to migrate to Lite. This is the only needed parameter when migrating an account to Lite. string
first_name First name of the user holder. string
last_name Last name of the user holder. string
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the email account changes. string (url)
{
  "success": true, 
  "id": "55555aaaaa66666bbbbb7777", 
  "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777", 
  "source": {
    "label": "foxmulder@email.com::email", 
    "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/folxmulder%3A%3Aemail"
  }, 
  "email_account": {
    "label": "foxmulder@email.com::email", 
    "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/folxmulder%3A%3Aemail"
  }
 }

Additional emails accounts

Use this endpoint to add a email account to an existing user. A user id is required to add a email account to an existing user.

HTTP request

POST lite/users/:id/email_accounts

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
email The primary email address used to receive emails for this user. string
server Name of IP of the IMAP server, eg. imap.email.com. Required when creating a email account and user in a single call. string
username The username used to authenticate an IMAP connection. On some servers, this is the same thing as the primary email address. string
use_ssl Set to 1 if you want SSL encryption to be used when opening connections to the IMAP server. Any other value will be considered as “do not use SSL”. Required when creating a email account and user in a single call. integer
port Port number to connect to on the server. For most servers, SSL is 993, and unencrypted (non-SSL) is 143. Required when creating a email account and user in a single call. integer
type Currently, the only supported type is IMAP. Required when creating a email account and user in a single call. string
password Password for this email account. Required when creating a email account and user in a single call. Ignored if any of the provider_* parameters are set below. string
provider_refresh_token An OAuth2 refresh token obtained from the IMAP user provider to authenticate this email user. Required if using oauth when creating a email account and user in a single call. string
provider_consumer_key The OAuth2 Client ID used to obtain the the refresh token for the above user. Required if using oauth when creating a email account and user in a single call. That consumer key and secret must be configured in your Context.IO user, see oauth_providers string
{
  "success": true, 
  "label": "foxmulder::email", 
  "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aemail", 
  "emailAccountId": "foxmulder::email"
}

Connect tokens wizard

Connect tokens are a feature we provide to facilitate user creation. Our connect tokens feature handles:

The connect token request returns a “browser_redirect_url” in its response. This is a public URL that requires no session or further authentication to be served. That URL is valid for a period of up to 24 hours from the creation of the “connect_token” (see the “expires” property in the “GET connect_token” response).

If, for some reason, a user tries to use it beyond that expiration period, you’ll simply need to request a new connect_token for the same email address.

HTTP request

POST lite/connect_tokens

Required parameters

Parameter Description Type
callback_url When the user’s mailbox is connected to your API key, the browser will call this url (GET). This call will have a parameter called contextio_token indicating the connect_token related to this callback. You can then do a get on this connect_token to obtain details about the user and email account created through that token and save that user id in your own user data. string (url)

Optional parameters

Parameter Description Type
email The email address of the user to be added. If specified, the first step of the connect UI where users are prompted for their email address, first name and last name is skipped. string
first_name First name of the user holder. string
last_name Last name of the user holder. string
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the email account changes. string (url)
{
  "success": true, 
  "token": "12345abcdef67890", 
  "resource_url": "https://api.context.io/lite/connect_tokens/12345abcdef67890", 
  "browser_redirect_url": "https://connect.context.io/api/lite/connect_tokens/12345abcdef67890?developer_key=5555555555555555555555555&branding_url=&branding_width=&branding_height=&branding_tagline="
}

Get connect token details

Getting data about a connect token will tell you:

HTTP requests

GET lite/connect_tokens/:token

Required parameters

Parameter Description Type
token The unique random token used for the graphical user creation process string

Unused token

{
  "token": "12345abcdef67890", 
  "account_lite": true, 
  "created": 1234567890, 
  "used": 0, 
  "callback_url": "https://your-website.com", 
  "expires": 1234567890, 
  "resource_url": "https://api.context.io/lite/connect_tokens/12345abcdef67890"
}

Used token

{
  "token": "12345abcdef67890", 
  "account_lite": true, 
  "created": 1234567890, 
  "used": 1234567890, 
  "callback_url": "https://your-website.com", 
  "user": {
    "id": "55555aaaaa66666bbbbb7777", 
    "email_accounts": [
      {
        "server": "imap.email.com", 
        "label": "foxmulder::email", 
        "username": "foxmulder@email.com", 
        "port": 993, 
        "use_ssl": true, 
        "type": "imap", 
        "authentication_type": "oauth2", 
        "status": "OK", 
        "status_message": null, 
        "status_callback_url": null, 
        "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aaol"
      }
    ], 
    "email_addresses": [
      "foxmulder@email.com"
    ], 
    "created": 1234567890, 
    "first_name": "foxmulder@email.com", 
    "last_name": "", 
    "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777"
  }, 
  "email_account_id": "foxmulder::email", 
  "expires": false, 
  "resource_url": "https://api.context.io/lite/connect_tokens/12345abcdef67890"
}

Listing connect tokens

List tokens for a user

Use this call to list all connect tokens associated with a user (used or unused).

HTTP request

GET lite/users/:id/connect_tokens

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer

List connect tokens for an email account

Use this call to list all connect tokens associated with an email account (used or unused).

HTTP request

GET lite/users/:id/email_accounts/:label/connect_tokens

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
label The label property of the email account instance. string
  {
    "token": "12345abcdef67890", 
    "account_lite": true, 
    "created": 1234567890, 
    "used": 1234567890, 
    "callback_url": "https://your-website.com", 
    "user": {
      "id": "55555aaaaa66666bbbbb7777", 
      "email_accounts": [
        {
          "server": "imap.email.com", 
          "label": "foxmulder::email", 
          "username": "foxmulder@email.com", 
          "port": 993, 
          "use_ssl": true, 
          "type": "imap", 
          "authentication_type": "oauth2", 
          "status": "OK", 
          "status_message": null, 
          "status_callback_url": null, 
          "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aaol"
        }
      ], 
      "email_addresses": [
        "foxmulder@email.com"
      ], 
      "created": 1234567890, 
      "first_name": "Fox", 
      "last_name": "Mulder", 
      "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777"
    }, 
    "email_account_id": "foxmulder::email", 
    "expires": false, 
    "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/connect_tokens/12345abcdef67890"
  }

Get user details

Getting details at the user level will give you:

HTTP request

GET lite/users/:id

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
{
  "id": "55555aaaaa66666bbbbb7777", 
  "email_accounts": [
    {
      "server": "imap.email.com", 
      "label": "foxmulder@email.com::email", 
      "username": "foxmulder@email.com", 
      "port": 993, 
      "use_ssl": true, 
      "type": "imap", 
      "authentication_type": "password", 
      "status": "OK", 
      "status_message": null, 
      "status_callback_url": null, 
      "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/folxmulder%3A%3Aemail"
    }, 
    {
      "server": "imap.email.com", 
      "label": "foxmulder::email", 
      "username": "foxmulder@email.com", 
      "port": 993, 
      "use_ssl": true, 
      "type": "imap", 
      "authentication_type": "oauth2", 
      "status": "OK", 
      "status_message": null, 
      "status_callback_url": null, 
      "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aemail"
    }
  ], 
  "email_addresses": [
    "foxmulder@email.com", 
    "foxmulder@email.com"
  ], 
  "created": 12345678901, 
  "first_name": "Fox", 
  "last_name": "Mulder", 
  "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777"
}

List all user email accounts

If the user has more than once email account, this endpoint will list all email accounts associated with the user. Optional parameters will allow you to filter by email account status.

HTTP request

“GET lite/users/:id/email_accounts”

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer

Optional parameters

Parameter Description Type
status Only return email accounts whose status is of a specific value. Possible statuses are: INVALID_CREDENTIALS, CONNECTION_IMPOSSIBLE, OK, TEMP_DISABLED and DISABLED string
status_ok Set to 0 to get email accounts that are not working correctly. Set to 1 to get those that are. integer

Getting details of a specific email account

The name of a email account in Context.IO is called a “label”. The label will be included in the response when you get user or email account details and looks something like “"email::provider”“.

You can use the integer "0” as shorthand for the first label on the user (subsequent labels don’t have a shorthand, a full label will need to be used).

HTTP request

GET lite/users/:id/email_accounts/:label

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
label The label property of the email account instance. string
 {
    "server": "imap.email.com", 
    "label": "foxmulder@email.com::email", 
    "username": "foxmulder@email.com", 
    "port": 993, 
    "use_ssl": true, 
    "type": "imap", 
    "authentication_type": "oauth2", 
    "status": "OK", 
    "status_message": null, 
    "status_callback_url": null, 
    "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/folxmulder%3A%3Aemail"
  }, 
  {
    "server": "imap.email.com", 
    "label": "foxmulder::email", 
    "username": "foxmulder@email.com", 
    "port": 993, 
    "use_ssl": true, 
    "type": "imap", 
    "authentication_type": "oauth2", 
    "status": "OK", 
    "status_message": null, 
    "status_callback_url": null, 
    "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aemail"
  }

Listing folders

List folders for a given email account.

HTTP request

GET lite/users/:id/email_accounts/:label/folders

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
label The label property of the email account instance. You can use 0 as an alias for the first email account of a user. string

Getting an individual folder

Get information about a given folder such as number of messages, number of unseen messages, and other attributes.

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
label The label property of the email account instance. You can use 0 as an alias for the first email account of a user. string
folder The full folder path using / as the path hierarchy delimiter. string
{
    "name": "Trash", 
    "nb_messages": 0, 
    "nb_unseen_messages": 0, 
    "delimiter": "/", 
    "symbolic_name": "\\Trash", 
    "xlist_name": "\\Trash", 
    "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/folxmulder%3A%3Aemail/folders/Trash"
}

Optional parameters

Parameter Description Type
delimeter If / isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delim parameter to tell us what you’re using. string

Listing messages

To list messages, you must know which user, label, and folder to list messages for.

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder/messages

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
label The label property of the email account instance. string
folder The full folder path using / as the path hierarchy delimiter. string

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string
include_body Set to 1 to include message bodies in the result. Since message bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
include_headers Can be set to 0 (default), 1 or raw. If set to 1, complete message headers, parsed into an array, are included in the results. If set to raw, the headers are also included but as a raw unparsed string. Since full original headers bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter. mixed
include_flags Set to 1 to include IMAP flags of messages in the result. Since message flags must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
body_type Used when include_body is set to get only body parts of a given MIME-type (for example text/html) string
limit The maximum number of results to return. The maximum limit is 100. The default if no limit is provided is 25. integer
offset Start the list at this offset (zero-based). integer

Getting an individual message

Get an individual message based on a “message_id” or “email_message_id”.

“message_id”: This is typically the same as the “email_message_id”, although sometimes you might see an ID such as “cio-1234-5678”. This is a Context.IO generated ID, as sometimes, some IMAP providers don’t use persistent message IDs, so we have to create our own.

“email_message_id”: This is an RFC 822 “Message-ID” pulled from the message header’s. Since this “email_message_id” is generated by the IMAP mailbox provider, this “email_message_id” is persistent across users / email accounts.

You should be able to use either the “message_id” or “email_message_id” when fetching a message via the API. There are some cases where the “email_message_id” may be empty or null if the IMAP provider doesn’t use persistent message IDs. In this case, we recommend you use the “message_id” as a back-up with the “cio-” generated message ID, if available.

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
label The label property of the email account instance. string
folder The full folder path using / as the path hierarchy delimiter. string
message_id Unique id of a message. This can be the “message_id” or “email_message_id” property of the message. The “gmail_message_id” (prefixed with gm-) can also be used. integer

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string
include_body Set to 1 to include the message body in the result. Since the body must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
include_headers Can be set to 0 (default), 1 or raw. If set to 1, complete message headers, parsed into an array, are included in the results. If set to raw, the headers are also included but as a raw unparsed string. Since full original headers bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
include_flags Set to 1 to include IMAP flags for this message in the result. Since message flags must be retrieved from the IMAP server, expect a performance hit when setting this parameter. integer
body_type Used when include_body is set to get only body parts of a given MIME-type (for example text/html) string
{
  "sent_at": 1234567890, 
  "addresses": {
    "from": [
      {
        "name": "Fox Mulder", 
        "email": "foxmulder@email.com"
      }
    ], 
    "sender": [
      {
        "name": "Dana Scully", 
        "email": "danascully@email.com"
      }
    ], 
    "reply_to": [
      {
        "name": "Dana Scully", 
        "email": "danascully@email.com"
      }
    ], 
    "to": [
      {
        "name": "Fox Mulder", 
        "email": "foxmulder@email.com"
      }
    ], 
    "cc": [ ], 
    "bcc": [ ]
  }, 
  "subject": "I want to believe", 
  "email_message_id": "<12345_abcde@email.com>", 
  "message_id": "55555444446666677778888", 
  "list_headers": [ ], 
  "in_reply_to": null, 
  "references": [ ], 
  "attachments": [
    {
      "size": 812176, 
      "type": "image/png", 
      "body_section": "2", 
      "file_name": "Screen Shot.png", 
      "content_disposition": "ATTACHMENT", 
      "content_id": null, 
      "attachment_id": 1, 
      "x_attachment_id": "f_j3keqeoq0", 
      "encoding": "BASE64"
    }
  ], 
  "bodies": [
    {
      "body_section": "1.1", 
      "type": "text/plain", 
      "encoding": "8BIT", 
      "size": 6
    }, 
    {
      "body_section": "1.2", 
      "type": "text/html", 
      "encoding": "8BIT", 
      "size": 27
    }
  ], 
  "received_headers": [
    "by 10.12.129.196 with SMTP id 4csp1126258qve;        Mon, 01 Jan 1999 10:25:45 -0700 (PDT)", 
    "from 0-0-0.email.com (0-0-0.email.com. [0.0.0.0])        by mx.email.com with ESMTPS id o51si32126764qtc.263.2017.06.05.10.25.45        for <foxmulder@email.com>        (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);        Mon, 01 Jan 1999 10:25:45 -0700 (PDT)", 
    "by 0-0-0.email.com with SMTP id 00000000.0        for <foxmulder@email.com>; Mon, 01 Jan 1999 10:25:45 -0700 (PDT)", 
    "by 0.0.0.0 with HTTP; Mon, 5 Jun 2017 10:25:44 -0700 (PDT)"
  ], 
  "folders": [
    "INBOX", 
    "\\Inbox"
  ], 
  "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aemail/folders/Inbox/messages/%3C12345_abcde%40email.com%3E"
}

List attachments

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id/attachments

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
label The label property of the email account instance. string
folder The full folder path using / as the path hierarchy delimiter. string
message_id Unique id of a message. This can be the “message_id” or “email_message_id” property of the message. The “gmail_message_id” (prefixed with gm-) can also be used. integer

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string
  {
    "size": 812176, 
    "type": "image/png", 
    "body_section": "2", 
    "file_name": "Screen Shot 2017-06-05 at 12.24.41 PM.png", 
    "content_disposition": "ATTACHMENT", 
    "content_id": null, 
    "attachment_id": 1, 
    "x_attachment_id": "f_j3keqeoq0", 
    "encoding": "BASE64"
  }

Getting a specific attachment in a message

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id/attachments/:attachment_id

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key. integer
label The label property of the email account instance. string
folder The full folder path using / as the path hierarchy delimiter. string
message_id Unique id of a message. This can be the “message_id” or “email_message_id” property of the message. The “gmail_message_id” (prefixed with gm-) can also be used. integer
attachment_id The index of the file attachment. integer

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string

The response from this call is the file itself

Get message body

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id/body

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string
type Used when include_body is set to get only body parts of a given MIME-type (for example text/html) string

Get message flags

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id/flags

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string
{
  "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aemail/folders/Inbox/messages/%3C12345_abcde%40email.com%3E/flags", 
  "flags": {
    "read": true, 
    "answered": false, 
    "flagged": false, 
    "draft": false, 
    "raw": [
      "\\Seen"
    ]
  }
}

Get message headers

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id/headers

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string
raw By default, this returns messages headers parsed into an object. Set this parameter to 1 to get raw unparsed headers. integer
{
  "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aemail/folders/Inbox/messages/%3C12345_abcde%40email.com%3E/headers", 
  "headers": {
    "delivered-to": [
      "foxmulder@email.com"
    ], 
    "received": [
      "by 0.0.0.0 with SMTP id 00000000; Mon, 01 Jan 1999 10:25:45 -0700 (PDT)", 
      "from 0-0-0.email.com (0-0-0.email.com. [0.0.0.0]) by mx.email.com with ESMTPS id 0.0.0.0 for <foxmulder@email.com> (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 01 Jan 1999 10:25:45 -0700 (PDT)", 
      "by 0-0-0.email.com with SMTP id 00000000.0 for <foxmulder@email.com>; Mon, 01 Jan 1999 10:25:45 -0700 (PDT)", 
      "by 0.0.0.0 with HTTP; Mon, 5 Jun 2017 10:25:44 -0700 (PDT)"
    ], 
    "x-received": [
      "by 0.0.0.0 with SMTP id 000000000000000000 000000000000000000000; Mon, 01 Jan 1999 10:25:45 -0700 (PDT)", 
      "by 0.0.0.0 with SMTP id 000000000000000000 000000000000000000000; Mon, 01 Jan 1999 10:25:45 -0700 (PDT)"
    ], 
    "arc-seal": [
      "i=1; a=rsa-sha256; t=0000000; cv=none; d=email.com; s=arc-00000000; 000000000000000000 000000000000000000000"
    ], 
    "arc-message-signature": [
      "i=1; a=rsa-sha256; c=relaxed/relaxed; d=email.com; s=arc-00000000; h=to:subject:message-id:date:from:mime-version:dkim-signature :arc-authentication-results; 000000000000000000 000000000000000000000"
    ], 
    "arc-authentication-results": [
      "i=1; mx.email.com; dkim=pass header.i=@email.com; spf=pass (email.com: domain of foxmulder@email.com designates 0:0:0:0::0 as permitted sender) smtp.mailfrom=foxmulder@email.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=email.com"
    ], 
    "return-path": [
      "<foxmulder@email.com>"
    ], 
    "received-spf": [
      "pass (email.com: domain of foxmulder@email.com designates 0.0.0.0 as permitted sender) client-ip=0.0.0.0;"
    ], 
    "authentication-results": [
      "mx.email.com; dkim=pass header.i=@email.com; spf=pass (email.com: domain of foxmulder@email.com designates 0.0.0.0 as permitted sender) smtp.mailfrom=foxmulder@email.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=email.com"
    ], 
    "dkim-signature": [
      "v=1; a=rsa-sha256; c=relaxed/relaxed; d=email.com; s=00000000; h=mime-version:from:date:message-id:subject:to; 000000000000000000 000000000000000000000"
    ], 
    "x-google-dkim-signature": [
      "v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=00000000; h=x-gm-message-state:mime-version:from:date:message-id:subject:to; 000000000000000000 000000000000000000000"
    ], 
    "x-gm-message-state": [
      "000000000000000000 000000000000000000000"
    ], 
    "mime-version": [
      "1.0"
    ], 
    "from": [
      "Dana Scully <danascully@email.com>"
    ], 
    "date": [
      "Mon, 01 Jan 1999 10:25:45 -0700 (PDT)"
    ], 
    "message-id": [
      "<12345_abcde@email.com>"
    ], 
    "subject": [
      "I want to believe"
    ], 
    "to": [
      "foxmulder@email.com"
    ], 
    "content-type": [
      "multipart/mixed; boundary=\"000000000000000000000\""
    ]
  }
}

Get the raw message

This call returns the RFC 822 raw message from the IMAP server.

HTTP request

GET lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id/raw

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string

Raw RFC 822 message

Mark a message as read / unread

Mark the message as read

HTTP request

POST lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id/read

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string

Mark the message as unread

HTTP request

DELETE lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id/read

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string
{
"success": true
}

Moving messages

This call allows you to move a message between folders.

HTTP request

PUT lite/users/:id/email_accounts/:label/folders/:folder/messages/:message_id

Required parameters

Parameter Description Type
new_folder_id Specifies the destination folder for the message move. string

Optional parameters

Parameter Description Type
delimeter If “/” isn’t fancy enough as a hierarchy delimiter when specifying the folder you want to obtain, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using. string
{
  "success": true
}

Deleting a message

It is not possible currently in the Lite version of the API to delete messages from a mailbox altogether, but you can use the move message endpoint as described above to move a message to the user’s Trash folder.

Webhooks

If you would like to receive notifications when a new message is received in a mailbox, you should use webhooks. Learn more about webhooks here.

A webhook is an HTTP callback that is triggered based on an event (receiving a message, sending a message, etc). If you setup a webhook, we will peform a callback to a callback URL on your domain via HTTP POST request.

You can setup webhooks at the user level, or at the application level.

User level webhooks

Webhooks set at the user level are applicable only to the user on which the webhook is set. User level webhooks should be used for cases when you will be monitoring things that are very specific to each individual user.

Create a user level webhook

HTTP Request

POST lite/users/:id/webhooks

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key integer
callback_url A valid URL Context.IO calls when a matching message is found. The callback URL is called with an HTTP POST with message information in request body, see receiving webhook callbacks. string
failure_notif_url (DEPRECATED) A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can’t re-establish it. string

Optional parameters

Parameter Description Type
filter_to Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_from Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_cc Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses. string
filter_subject Check for new messages with a subject matching a given string or regular expresion string
filter_thread Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id of an existing message currently in the thread. string
filter_file_name Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the attachment list call. string
filter_folder_added Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_to_domain Check for new messages sent to a given domain. Also accepts a comma delimited list of domains. string
filter_from_domain Check for new messages sent from a given domain. Also accepts a comma delimited list of domains. string
include_body Set to 1 or raw to include message bodies in the result. integer
body_type Required to be set when “include_body” is set to get only body parts of a given MIME-type. Acceptable values are “text/html” or “text/plain”. string
include_header Set to 1 or raw to include message headers in the result. mixed
receive_all_changes By default, we only send a webhook notification on the first event of a message (i.e. when a message is received or sent). Subsequent changes of a specific message do not trigger a webhook (i.e. if a message changes folders). When this parameter is set to 1, we will send all events related to a message. integer
receive_drafts Set to 1, you will receive messages that are flagged as “\Drafts” in Gmail integer

List all webhooks set on a specific user

HTTP Request

“GET lite/users/:id/webhooks”

List all webhooks set on a specific user.

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key integer

Get information about a specific user level webhook

Get information about a single user level webhook, such whether it is active and what filters are set on the webhook.

HTTP Request

GET lite/users/:id/webhooks/:webhook_id

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key integer
webhook_id Unique id of a user level webhook integer

Edit an existing user level webhook

Edit an existing user level webhook. Please note changes to an existing webhook are not appended but overwritten.

HTTP Request

POST lite/users/:id/webhooks/:webhook_id

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key integer
webhook_id Unique id of a user level webhook integer

Optional parameters

Parameter Description Type
callback_url A valid URL Context.IO calls when a matching message is found. The callback URL is called with an HTTP POST with message information in request body, see receiving webhook callbacks. string
failure_notif_url (DEPRECATED) A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can’t re-establish it. string
active By default, webhooks are set to active when first created. Set to 0 to temporarily stop receiving callbacks for this webhook. Set to 1 again to resume. integer
filter_to Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_from Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_cc Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses. string
filter_subject Check for new messages with a subject matching a given string or regular expresion string
filter_thread Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id of an existing message currently in the thread. string
filter_file_name Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the attachment list call. string
filter_folder_added Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_to_domain Check for new messages sent to a given domain. Also accepts a comma delimited list of domains. string
filter_from_domain Check for new messages sent from a given domain. Also accepts a comma delimited list of domains. string
include_body Set to 1 or raw to include message bodies in the result. integer
body_type Required to be set when “include_body” is set to get only body parts of a given MIME-type. Acceptable values are “text/html” or “text/plain”. string
include_header Set to 1 or raw to include message headers in the result. mixed
receive_all_changes By default, we only send a webhook notification on the first event of a message (i.e. when a message is received or sent). Subsequent changes of a specific message do not trigger a webhook (i.e. if a message changes folders). When this parameter is set to 1, we will send all events related to a message. integer
receive_drafts Set to 1, you will receive messages that are flagged as “\Drafts” in Gmail integer

Delete a specific user level webhook

HTTP Request

DELETE lite/users/:id/webhooks/:webhook_id

Required parameters

Parameter Description Type
id Unique id of a user accessible through your API key integer
webhook_id Unique id of a user level webhook integer

Application level webhooks

Webhooks set at the application level apply to all users in your userbase. Application level webhooks are encouraged over user level webhooks when you:

Application level webhooks encourage a more DRY approach to using the Context.IO API.

Create an application level webhook

HTTP Request

POST lite/webhooks

Required parameters

Parameter Description Type
callback_url A valid URL Context.IO calls when a matching message is found. The callback URL is called with an HTTP POST with message information in request body, see receiving webhook callbacks. string
failure_notif_url (DEPRECATED) A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can’t re-establish it. string

Optional parameters

Parameter Description Type
active By default, webhooks are set to active when first created. Set to 0 to temporarily stop receiving callbacks for this webhook. Set to 1 again to resume. integer
filter_to Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_from Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_cc Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses. string
filter_subject Check for new messages with a subject matching a given string or regular expresion string
filter_thread Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id of an existing message currently in the thread. string
filter_file_name Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the attachment list call. string
filter_folder_added Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_to_domain Check for new messages sent to a given domain. Also accepts a comma delimited list of domains. string
filter_from_domain Check for new messages sent from a given domain. Also accepts a comma delimited list of domains. string
include_body Set to 1 or raw to include message bodies in the result. integer
body_type Required to be set when “include_body” is set to get only body parts of a given MIME-type. Acceptable values are “text/html” or “text/plain”. string
include_header Set to 1 or raw to include message headers in the result. mixed
receive_all_changes By default, we only send a webhook notification on the first event of a message (i.e. when a message is received or sent). Subsequent changes of a specific message do not trigger a webhook (i.e. if a message changes folders). When this parameter is set to 1, we will send all events related to a message. integer
receive_drafts Set to 1, you will receive messages that are flagged as “\Drafts” in Gmail integer
receive_historical Set to 1, we will perform a backscan of a user when a new user is added and send messages from new to old to your callback URL. integer

List all application level webhooks

List all application level webhooks.

HTTP Request

GET lite/webhooks

Get information about a specific application level webhook

Get information about a single application level webhook, such whether it is active and what filters are set on the webhook.

Required parameters

Parameter Description Type
webhook_id Unique id of an application level webhook integer

Edit a specific application level webhook

Edit an existing webhook. Please note changes to an existing webhook are not appended but overwritten.

HTTP Request

POST lite/webhooks/:webhook_id

Required parameters

Parameter Description Type
webhook_id Unique id of an application level webhook integer

Optional parameters

Parameter Description Type
active By default, webhooks are set to active when first created. Set to 0 to temporarily stop receiving callbacks for this webhook. Set to 1 again to resume. integer
filter_to Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_from Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses. string
filter_cc Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses. string
filter_subject Check for new messages with a subject matching a given string or regular expresion. string
filter_thread Check for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id of an existing message currently in the thread. string
filter_file_name Check for new messages where a file whose name matches the given string is attached. Supports wildcards and regular expressions like the file_name parameter of the attachment list call. string
filter_folder_added Check for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track. string
filter_to_domain Check for new messages sent to a given domain. Also accepts a comma delimited list of domains. string
filter_from_domain Check for new messages sent from a given domain. Also accepts a comma delimited list of domains. string
include_body Set to 1 or raw to include message bodies in the result. mixed
body_type Required to be set when “include_body” is set to get only body parts of a given MIME-type. Acceptable values are “text/html” or “text/plain”. string
include_header Set to 1 or raw to include message headers in the result. mixed
receive_all_changes By default, we only send a webhook notification on the first event of a message (i.e. when a message is received or sent). Subsequent changes of a specific message do not trigger a webhook (i.e. if a message changes folders). When this parameter is set to 1, we will send all events related to a message. integer
receive_drafts Set to 1, you will receive messages that are flagged as “\Drafts” in Gmail. integer
receive_historical Set to 1, we will perform a backscan of a user when a new user is added and send messages from new to old to your callback URL. integer

Delete a specific application level webhook

Delete an existing application level webhook.

HTTP Request

DELETE lite/webhooks/:webhook_id

Required parameters

Parameter Description Type
webhook_id Unique id of an application level webhook integer

Webhook created response

{
  "success": true, 
  "webhook_id": "55555ddddd66666eeeee7777", 
  "resource_url": "https://api.context.io/lite/..."
}

Webhook details response

  {
    "callback_url": "https://your-callback.com", 
    "failure_notif_url": "https://your-callback.com", 
    "active": true, 
    "webhook_id": "55555ddddd66666eeeee7777", 
    "resource_url": "https://api.context.io/lite/..."
  }

Edit webhook response

{
  "success": true, 
  "resource_url": "https://api.context.io/lite/..."
}

Delete webhook response

{
  "success": true 
}

Receiving webhook callbacks

When an event matching the filters set for your webhook occurs in the mailbox, we do an HTTP POST request to your callback_url.

When you receive the POST request from our servers, it is important to respond to it with a 200 before doing any additional processing.

Authenticating requests to your callback URL

You can validate that a request to your callback URL is a valid request from Context.IO using the combination of the timestamp, token and signature properties in the body. The signature is the HMAC-SHA256 hash of the string formed by concatenating the timestamp and token using your Context.IO OAuth secret as the hashing key.

Issues with Apache and mod_security

The mod_security module for Apache decided application/json is an exotic Content-type for the body of a POST request and rejects them by default, typically with a 406 status code. To avoid having Apache reject WebHook callbacks, you need to either change default mod_security configs or disable it for your domain. You can learn more about this here.

Sample webhook payload

{"account_id":"55555aaaaa66666bbbbb7777","webhook_id":"55555ddddd66666eeeee7777","timestamp":1234567890,"message_data":{"message_id":"55555444446666677778888","email_message_id":"\u003c12345_abcde@email.com\u003e","addresses":{"from":{"email":"danascully@email.com","name":"Dana Scully"},"to":[{"email":"foxmulder@email.com"}],"return_path":[{"email":"danascully@email.com"}]},"person_info":{"danascully@email.com":{"thumbnail":"https://secure.gravatar.com/avatar/contact.png"},"danascully@email.com":{"thumbnail":"https://secure.gravatar.com/avatar/contact.png"}},"date_received":1234567890,"subject":"I want to believe","folders":["INBOX","\\Inbox"],"bodies":[{"type":"text/plain","charset":"utf-8","body_section":"1"},{"type":"text/html","charset":"utf-8","body_section":"2"}],"email_accounts":[{"label":"foxmulder::email","resource_url":"https://api.context.io/2.0/users/5931cebae5c6bf22ea47ad53/email_accounts/scullyd35%3A%3Agmail","folder":"[Gmail]/All Mail","uid":103}],"flags":{"flagged":false,"answered":false,"draft":false,"seen":false},"date":1496436749,"references":[],"files":[],"sources":[{"label":"scullyd35::gmail","resource_url":"https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail","folder":"Inbox","uid":101}]},"token":"xxxxx","signature":"xxxxx"}

Reconnecting email accounts

There will be times when a email account gets disconnected from Context.IO. Causes for disconnection are always due to a change in credentials on the end-user’s side. Causes for disconnetion include:

Checking email account status

When a change in credentials happens and we lose our ability to connect to an email account, we mark the email account as “DISABLED”.

When you perform a request to the API, we include the user’s email account status in the response headers as “X-Contextio-email account-Status”.

An email account in “OK” status will display as follows in the headers we return:

X-Contextio-email account-Status: https://api.context.io/lite/users/:id/email accounts/:email account OK

An email account in “DISABLED” status will display as follows in the headers we return:

X-Contextio-email account-Status: https://api.context.io/lite/users/:id/email accounts/:email account DISABLED

Manually check user status

You can ‘manually’ check the status of a specific email account via the following request:

GET lite/users/:id/email_accounts/:label

You can also check the status of all email accounts associated to a user via this request:

GET lite/users/:id

The API will return “status” and “status_message” values as part of the response, which will provide details on the status of a email account.

{
  "server": "imap.email.com", 
  "label": "foxmulder::email", 
  "username": "foxmulder@email.com", 
  "port": 993, 
  "use_ssl": true, 
  "type": "imap", 
  "authentication_type": "oauth2", 
  "status": "OK", 
  "status_message": null, 
  "status_callback_url": null, 
  "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aemail"
}

Status callback push notifications

Checking for the status of an email account manually is not ideal, as such, we provide a way for developers to receive notifications when an email account goes into “DISABLED” status by setting a “status_callback_url”. This “status_callback_url” is an endpoint on the developer’s side where we will perform a callback when a email account goes into “DISABLED” status.

You can:

Setting a status_callback_url_ at the email account level

You can include a “status_callback_url” param when you create a email account via a “POST lite/users/:id/email accounts/:label” request, or you can add it after email account creation on the same endpoint by passing in a “status_callback_url” value.

HTTP Request

POST lite/users/:id/email accounts/:label

Optional parameters

Parameter Description Type
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the email account changes. string (url)

Setting a status_callback_url_ at the application level

You can set a “global” “status_callback_url” at the application level, where we will send all status postbacks to, if you prefer to receive all callbacks on the same endpoint.

HTTP Request

POST lite/users/:id/email accounts/:label

Optional parameters

Parameter Description Type
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the email account changes. string (url)

status_callback_url payload for DISABLED users

{"account_id":"55555aaaaa66666bbbbb7777","user_id":"55555aaaaa66666bbbbb7777","server_label":"foxmulder::email","email_account":"foxmulder::email","timestamp":1234567890,"failure":"permanent"}

status_callback_url payload for cleared users

{"account_id":"55555aaaaa66666bbbbb7777","user_id":"55555aaaaa66666bbbbb7777","server_label":"foxmulder::email","email_account":"foxmulder::email","timestamp":1234567890,"failure":"cleared"}

Discovering IMAP settings

If you prefer to handle your own authentication and add users or email accounts manually, you may want to check for IMAP configuration settings to add users. The Discovery endpoint returns known IMAP configuration settings given an email address.

This endpoint checks IMAP server information in the following 3 places:

The information from the Discovery endpoint should not be treated as a single email account of truth, as these settings can be changed by the provider at any time without notice.

HTTP Request

GET lite/discovery

Required parameters

Parameter Description Type
email account_type The type of email account you want to discover settings for. Right now, the only supported email account type is “IMAP” string
email An email address you want to discover IMAP settings for. Make sure email account_type is set to “IMAP”. string
{
  "email": "danascully@email.com", 
  "found": true, 
  "resource_url": "https://api.context.io/lite/discovery", 
  "type": "gmail", 
  "imap": {
    "server": "imap.email.com", 
    "username": "danascully@email.com", 
    "port": 993, 
    "use_ssl": true, 
    "oauth": true
  }, 
  "documentation": [ ]
}

Custom oauth providers

You can associate your own oauth provider keys with your Context.IO API key, in fact, we recommend all developers use their own oauth provider keys to authenticate users with.

Context.IO supports oauth for the following providers:

Oauth provider set-up

Google Create a new application via the Google Developer Console if you have not already. When handling your own oauth, you must make sure you ask for the right scope. To connect to the IMAP servers the scope must be full access “https://mail.email.com/”. See the Google documentation here. Also it is important to set the redirect URL. The redirect url you should use is “https://api.context.io/connect/oauth2callback”.

Microsoft Create a new applicaiton via the Microsoft Application Portal if you have not already. Click on “API Settings” and under redirect URLs, add the following URL, “https://{CIO OAuth Key}.api.context.io/connect/mslivecallback”, then click “Save”.

Get a list of oauth providers

List all oauth providers linked to your Context.IO API key.

HTTP Request

GET lite/oauth_providers

Add an oauth provider

HTTP Request

POST lite/oauth_providers

Required parameters

Parameter Description Type
type Identification of the OAuth2 provider. Possible values are GMAIL_OAUTH2 and MSLIVECONNECT. string
provider_consumer_key The OAuth2 Client ID string
provider_consumer_secret The OAuth2 Client Secret string

Get information about an oauth provider

“GET lite/oauth_providers/:key”

Required parameters

Parameter Description Type
key The consumer key for this external OAuth provider string

Delete an oauth provider

“DELETE lite/oauth_providers/:key”

Required parameters

Parameter Description Type
key The consumer key for this external OAuth provider string
  {
    "provider_consumer_key": "xxxxxxxxx.apps.googleusercontent.com", 
    "provider_consumer_secret": "xxx[...]xxx", 
    "type": "GMAIL_OAUTH2", 
    "resource_url": "https://api.context.io/lite/oauth_providers/xxxxxxxxx.apps.googleusercontent.com"
  }

Application level endpoints

Status callback URL

Set an application level status callback url

You can set “status_callback_url” at the application level. This means we will aggregate all status callbacks and post them all onto the same URL.

HTTP Request

POST app/status_callback_url

Required parameters

Parameter Description Type
status_callback_url If specified, we’ll make a POST request to this URL if the connection status of the email account changes. string (url)

To edit an existing status_callback_url, simply make a subsequent POST request to this same endpoint.

Delete an application level status callback url

HTTP Request

DELETE app/status_callback_url

View an existing status_callback_url

HTTP Request

GET app/status_callback_url

{
  "status_callback_url": "https://your-callback.com",
  "resource_url": "https://api.context.io/app/status_callback_url"
}

Logs

Webhook logs

Logs for webhook callbacks. Use these logs to troubleshoot of if you need to verify the receipt of a certain callback. Logs only go back previous 2 weeks.

Parameters

Parameter Description Type
account Only include logs of webhooks from the specified account id string
webhook_id Only include logs of webhooks with the specified webhook id string
timestamp_before Only include logs of webhooks before a given timestamp. integer (Unix timestamp)
timestamp_after Only include logs of webhooks after a given timestamp. integer (Unix timestamp)
status_code_from Only return webhook logs where the status code is greater than the number specified. For example 200) integer
status_code_to Only return webhook logs where the status code is less than the number specified. For example 300) integer
  {
    "user_id": "55555aaaaa66666bbbbb7777",
    "webhook_id": "55555ddddd66666eeeee7777",
    "callback_url": "https://your-callback.com",
    "email_message_id": "<12345_abcde@email.com>",
    "message_id": "55555444446666677778888",
    "received_status_code": "200",
    "timestamp": "1234567890"
  }

Call logs

Logs for calls from your API key.

Parameters

Parameter Description Type
account Only include logs of webhooks from the specified account id string
timestamp_before Only include logs of calls before a given timestamp. integer (Unix timestamp)
timestamp_after Only include logs of calls after a given timestamp. integer (Unix timestamp)
status_code_from Only return logs of calls where the status code is greater than the number specified. For example 200) integer
status_code_to Only return logs of call where the status code is less than the number specified. For example 500) integer
request_method Only return logs of calls where the http method is the one specified. For example, GET string
request_path Only return logs of calls where the request matches this search string. To use regular expressions instead of simple string matching, make sure the string starts and ends with / string
  {
    "request_ip": "0.0.0.0",
    "timestamp": "1234567890",
    "request_line": "GET /app/status_callback_url HTTP/1.1",
    "user_agent": "ContextIO-APIExplorer (PHP)",
    "http_return_code": "200",
    "response_size": "100",
    "user_id": "55555aaaaa66666bbbbb7777"
  }

Errors

Here is a list of error codes you may encounter in Context.IO and what they mean for working with our API.

Error Code Meaning
400 Bad Request – There is an issue in how the request was formed, your’re using a wrong parameter, or passinig in incorrect data in a parameter
401 Unauthorized – Your API key is wrong or you are not signing the request correctly
402 Payment Required – You’ve exceeded your user limit (see removing initial user limit)
403 Forbidden – You are passing a resource ID for the wrong version of the API (i.e. using 2.0 resource ID on Lite or viceversa)
404 Not Found – The specified resource could not be found, please ensure this resource exists
409 Conflict – There is already a resource with these same criteria. (i.e. you are attempting to create a duplicate resource)
412 Pre-condition failed – Account or user is currently in DISABLED status and we cannot make calls against the mailbox (see DISABLED status)
429 Too Many Requests – You’re exeeding your API rate limit (see API rate limits)
451 Unavailable for Legal Reasons – You are trying to add a user in an unsupported region
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

FAQs

What are your API rate limits?

Initial user limit

We impose an initial user limit of 100 users for developers on our free tier. This limit is lifted once a developer sends us a link to their privacy policy. Your privacy policy must be somewhere publiclly accessible, state that you are using Context.IO, and link to our opt-out page. Once this is done, contact us at support@context.io with a link to your privacy policy in order for us to remove the initial user limit.

Rate limits for 2.0

We restrict calls to IMAP to 30 calls to IMAP per user, per minute. We do this in order to keep IMAP from throttling. This limit cannot be lifted. Calls to IMAP are calls that do not hit our cache, such as:

Rate limits for Lite

Calls to IMAP in Lite are limited to 120 calls to IMAP per user, per minute. Calls to IMAP in Lite are:

What does DISABLED status mean?

The “DISABLED” status means we no longer have valid credentials for a user. You will need to obtain updated credentials from the user and update them on Context.IO.

You can learn more in general about how to handle disconnected accounts in this blog post.

What are your supported regions?

Due to a Russian data law enacted in 2016, we are no longer able to support developers or users based out of Russia. Read the full announcement here.

Have a question not answered here? Check out our support portal.

Mobile applications

If you are developing a mobile application, you may need to look into how to best authenticate your users onto the platform in the most secure way.

We highly recommend you set-up a proxy server to communicate between Context.IO and the mobile app. This means your mobile app would make requests against your proxy server, and your proxy server would make requests to Context.IO.

Advantages:

Enabling 3-legged authentication

If you do not want to set-up a proxy server to make calls against Context.IO, you will have to enable 3-legged authentication on your Context.IO developer key. This is not a self-serve operation. You will need to contact support@context.io and ask to switch your Context.IO API key to be 3-legged enabled.

Read more about 3-legged authentication here.