NAV Navbar

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

Name Location Type Description
email body string The primary email address used to receive emails in this account.

Optional parameters

Name Location Type Description
first_name body string First name of the account holder.
last_name body string Last name of the account holder.
server body string Name of IP of the IMAP server, eg. imap.gmail.com. Required when creating a source and account in a single call.
username body string 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.
use_ssl body integer 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.
port body integer 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.
type body string Currently, the only supported type is IMAP. Required when creating a source and account in a single call.
sync_all_folders body integer 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.
expunge_on_deleted_flag body integer By default, we don’t filter out messages flagged as deleted. Set this parameter to “1” to turn on this filtering.
password body string 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.
provider_refresh_token body string 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.
provider_consumer_key body string 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
callback_url body string (url) If specified, we’ll make a POST request to this URL when the initial sync is completed.
status_callback_url body string (url) If specified, we’ll make a POST request to this URL if the connection status of the source changes.
{
  "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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
email body string The primary email address used to receive emails in this account
username body string body
server body string Name of IP of the IMAP server, eg. imap.gmail.com
use_ssl body integer 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”
port body integer Port number to connect to on the server. For most servers, SSL is 993, and unencrypted (non-SSL) is 143.
type body string Currently, the only supported type is IMAP.

Optional parameters

Name Location Type Description
origin_ip body string IP address of the end user requesting the account to be created.
expunge_on_deleted_flag body integer By default, we don’t filter out messages flagged as deleted. Set this parameter to “1” to turn on this filtering.
sync_all_folders body integer 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.
raw_file_list body integer 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.
password body string Password for authentication on the IMAP server. Ignored if any of the provider_* parameters are set below.
provider_refresh_token body string An OAuth2 refresh token obtained from the IMAP account provider to authenticate this email account.
provider_consumer_key body string 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.
callback_url body string (url) If specified, we’ll make a POST request to this URL when the initial sync is completed.
status_callback_url body string (url) If specified, we’ll make a POST request to this URL if the connection status of the source changes.
{
  "success": true,
  "label": "foxmulder::email",
  "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail"
}

Delete an account or source

If you need to delete an account, you can do so by sending a DELETE request to the account instance endpoint. This will delete the account and all sources associated with it.

HTTP request

DELETE 2.0/accounts/:id/

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.

If you wish to only delete a certain source from the account, but not delete the account itself, you can send a DELETE request to the sources label instance endpoint.

HTTP request

DELETE 2.0/accounts/:id/sources/:label

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
label url string The label property of the source instance.
{
  "success": true
}

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

Name Location Type Description
callback_url body string (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.

Optional parameters

Name Location Type Description
email body string 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.
first_name body string First name of the account holder.
last_name body string Last name of the account holder.
source_callback_url body string If specified, we’ll make a POST request to this URL when the initial sync is completed.
source_expunge_on_deleted_flag body integer By default, we don’t filter out messages flagged as deleted. Set this parameter to “1” to turn on this filtering.
source_sync_all_folders body integer 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.
source_sync_folders body string By default, we filter out some folders like 'Deleted Items’ and 'Drafts’. Set this parameter to All,Trash to show the 'Deleted Items’ folder.
source_raw_file_list body integer 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.
status_callback_url body string (url) If specified, we’ll make a POST request to this URL if the connection status of the source changes.
{
  "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

Name Location Type Description
token url string The unique random token used for the graphical account creation process.

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
label url string The label property of the source instance.
{
    "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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
{
  "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

Name Location Type Description
id url string Unique id of an account accessible through your API key.

Optional parameters

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

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
label url string The label property of the source instance.
{
    "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

Name Location Type Description
id url string Unique id of an account accessible through your API key.

Optional parameters

Name Location Type Description
subject query string 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 /.
email query string Email address(es) 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. This accepts a single address or a comma separated list.
to query string Email address of a contact messages have been sent to.
from query string Email address of a contact messages have been received from.
cc query string Email address of a contact CC'ed on the messages.
bcc query string Email address of a contact BCC'ed on the messages.
folder query string 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.
source query string Filter messages by the account source label.
file_name query string 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
file_size_min query integer Search for files based on their size (in bytes).
file_size_max query integer Search for files based on their size (in bytes).
date_before query integer (Unix timestamp) 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.
date_after query integer (Unix timestamp) 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.
indexed_before query integer (Unix timestamp) 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.
indexed_after query integer (Unix timestamp) 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.
include_thread_size query integer Set to “1” to include thread size in the result.
include_body query integer 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.
include_headers query mixed 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.
include_flags query integer 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.
body_type query string Used when include_body is set to get only body parts of a given MIME-type (for example text/html)
include_source query integer 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.
sort_order query string The sort order of the returned results. Possible values are “asc” and “desc”
limit query integer The maximum number of results to return. The maximum limit is “100”. The default if no limit is provided is “25”.
offset query integer Start the list at this offset (zero-based).

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”).

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

HTTP request

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

Required parameters

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

Optional parameters

Name Location Type Description
include_thread_size query integer Set to “1” to include thread size in the result.
include_body query integer 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.
body_type query string Used when include_body is set to get only body parts of a given MIME-type (for example text/html).
include_headers query mixed 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.
include_flags query integer 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.
flag_seen query integer 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).
limit query integer The maximum number of results to return. The maximum limit is “100”. The default if no limit is provided is “25”.
offset query integer Start the list at this offset (zero-based).

Get 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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
message_id url string 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.

Optional parameters

Name Location Type Description
include_thread_size query integer Set to “1” to include thread size in the result.
include_body query integer 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.
include_headers query integer 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.
include_flags query integer 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.
body_type query string Used when include_body is set to get only body parts of a given MIME-type (for example text/html).
include_source query integer 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.
  {
    "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"
  }

Get message body

You can use this call to request the body of a specific message. Remember that you can also set “include_body=1” when making a call to GET messages, or even better, set your webhooks to “include_body=1” as well. This call goes straight to IMAP so be sure to stay within the IMAP call limit.

HTTP request

GET 2.0/accounts/:id/message/:message_id/body

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
message_id url string 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.
{
    "body_section": "1",
    "type": "text\/plain",
    "charset": "utf-8",
    "content": "I want to believe!\r\n"
}

Get message flags

This call lists all flags currently applied to this message.

HTTP request

GET 2.0/accounts/:id/message/:message_id/flags

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
message_id url string 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.
{
  "seen": true,
  "answered": false,
  "flagged": false,
  "deleted": false,
  "draft": false
}

Modify message flags

This call will allow you to set or unset flags for a specific message.

HTTP request

POST 2.0/accounts/:id/message/:message_id/flags

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
message_id url string 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.

Optional parameters

Name Location Type Description
seen body integer Message has been read. Set this parameter to “1” to set the flag, “0” to unset it.
answered body integer Message has been answered. Set this parameter to “1” to set the flag, “0” to unset it.
flagged body integer Message is “flagged” for urgent/special attention. Set this parameter to “1” to set the flag, “0” to unset it.
deleted body integer Message is “deleted” for later removal. An alternative way of deleting messages is to move it to the Trash folder. Set this parameter to “1” to set the flag, “0” to unset it.
draft body integer Message has not completed composition (marked as a draft). Set this parameter to “1” to set the flag, “0” to unset it.
{
  "success": true,
  "flags": {
    "seen": false,
    "answered": false,
    "flagged": false,
    "deleted": false,
    "draft": false
  }
}

Get message folders

This call returns the folder(s) a message appears in

HTTP request

GET 2.0/accounts/:id/message/:message_id/folders

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
message_id url string 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.
  {
    "name": "INBOX",
    "symbolic_name": "\\Inbox",
    "xlist_name": "\\Inbox"
  }

Get message headers

This call returns only the headers for this message. We send a parsed response by default, but you can also choose to get the raw RFC 822 headers.

HTTP request

GET 2.0/accounts/:id/message/:message_id/headers

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
message_id url string 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.

Optional parameters

Name Location Type Description
raw query integer By default, this returns messages headers parsed into an array. Set this parameter to “1” to get raw unparsed headers.

Parsed response

{
  "delivered-to": [
    "foxmulder@email.com"
  ],
  "received": [
    "by 00.000.000.000 with SMTP id 0000000; "Mon, 01 Jan 1995 00:00:00 +0000 (UTC)",
    "from email.com (email.com. [000.00.000.00]) by mx.email.com with SMTPS id 000000000 for <foxmulder@email.com>; "Mon, 01 Jan 1995 00:00:00 +0000 (UTC)"
  ],
  "x-received": [
    "by 00.000.00.00 with SMTP id 00000; Mon, 01 Jan 1995 00:00:00 +0000 (UTC)",
    "by 00.00.00.00 with SMTP id 00000; Mon, 01 Jan 1995 00:00:00 +0000 (UTC)"
  ],
  "arc-seal": [
    "i=1; a=rsa-sha256; t=123456789; cv=none; d-email.com; s=arc-20160816; 00000000000000=="
  ],
  "arc-message-signature": [
    "i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=to:from:subject:message-id:feedback-id:date:mime-version :dkim-signature:arc-authentication-results; 00000000000000000=="
  ],
  "arc-authentication-results": [
    "i=1; mx.email.com; dkim=pass header.i=@email.com header.s=20161025 header.b=eS1mj0ya; spf=pass (email.com: domain of 00000@email.com designates 000.00.000.00 as permitted sender) smtp.mailfrom=00000@email.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=email.com"
  ],
  "return-path": [
    "<00000@email.com>"
  ],
  "received-spf": [
    "pass (email.com: domain of 00000@email.com designates 000.00.000.00 as permitted sender) client-ip=000.00.000.00;"
  ],
  "authentication-results": [
    "mx.email.com; dkim=pass header.i=@email.com header.s=20161025 header.b=eS1mj0ya; spf=pass (email.com: domain of 000000@email.com designates 000.00.000.00 as permitted sender) smtp.mailfrom=00000@email.com; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=email.com"
  ],
  "dkim-signature": [
    "v=1; a=rsa-sha256; c=relaxed/relaxed; d=email.com; s=20161025; h=mime-version:date:feedback-id:message-id:subject:from:to; bh=HjokJGpNZdU/oIZ4X+nNi9qro54392a1tbTAJ1VBPkA=; b=eS1mj0yakZ/VvNg1jSJJhagtQlWEbjjCzSmWd9n6VMk9DhB9wnobJPqZqbmMudUiZo 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000=="
  ],
  "x-google-dkim-signature": [
    "v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:date:feedback-id:message-id:subject :from:to; 0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000=="
  ],
  "x-gm-message-state": [
    "ABCD/1234/EFGH"
  ],
  "mime-version": [
    "1.0"
  ],
  "date": [
    "Mon, 01 Jan 1995 00:00:00 +0000 (UTC)"
  ],
  "x-notifications": [
    "ABCD-1234-EFGH"
  ],
  "x-account-notification-type": [
    "123"
  ],
  "feedback-id": [
    "123:account-notifier"
  ],
  "message-id": [
    "<ABCD12345@email.com>"
  ],
  "subject": "I want to believe",
  "from": [
    "Dana Scully <danascully@email.com>"
  ],
  "to": [
    "foxmulder@email.com"
  ],
  "content-type": [
    "multipart/alternative; boundary=\"00112233445566778899\""
  ]
}

Raw response

RAW RFC-882 headers

Get message raw source

This endpoint returns the raw RFC 822 source message.

HTTP request

GET 2.0/accounts/:id/message/:message_id/source

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
message_id url string 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.
RAW RFC-882 source message

Get message thread

This endpoint returns the the entire thread of messages a message is in that Context.IO has access to. Replies in the thread from accounts not in Context.Io would not appear here.

HTTP request

GET 2.0/accounts/:id/message/:message_id/thread

Optional parameters

Name Location Type Description
include_body query integer 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.
include_headers query mixed 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.
include_flags query integer 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.
body_type query string Used when include_body is set to get only body parts of a given MIME-type (for example text/html).
include_source query integer 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.
sort_order query string The sort order of the returned results. Possible values are “asc” and “desc”.
limit query integer The maximum number of results to return. The maximum limit is “100”. The default if no limit is provided is “25”.
offset query integer Start the list at this offset (zero-based).
{
  "email_message_ids": [
    "<12345ABCDE@email.com>",
  ],
  "messages": [
    {
      "email_message_id": "<12345ABCDE@email.com>",
      "message_id": "55555444446666677778888",
      "addresses": {
        "from": {
          "email": "danascully@email.com",
          "name": "Dana Scully"
        },
        "to": [
          {
            "email": "foxmulder@email.com"
          }
        ],
        "reply_to": [
          {
            "email": "danascully@email.com"
          }
        ]
      },
      "folders": [
        "Inbox"
      ],
      "date": 1234567890,
      "date_indexed": 1234567890,
      "date_received": 1234567890,
      "subject": "I want to believe",
      "sources": [
        {
          "label": "foxmulder::email",
          "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%3Aemail"
        }
      ],
      "files": [ ],
      "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/messages/55555444446666677778888"
    }
  ]
}

Modifying or moving a message

This call allows you to copy or move a message between folders, or also change the message’s flags all at once. 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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
message_id url string 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.
dst_folder body string The folder within dst_source the message should be copied to.

Optional parameters

Name Location Type Description
dst_source body string Label of the source you want the message copied to. This field is required if you’re moving a message that already exists in one source of the account to another source of that account. If you only want to move the message to a different folder within the same source, dst_folder is sufficient.
move body integer By default, this calls copies the original message in the destination. Set this parameter to “1” to move instead of copy.
flag_seen body integer Message has been read. Set this parameter to “1” to set the flag, 0 to unset it.
flag_answered body integer Message has been answered. Set this parameter to “1” to set the flag, “0” to unset it.
flag_deleted body integer Message is “deleted” for later removal. An alternative way of deleting messages is to move it to the Trash folder. Set this parameter to “1” to set the flag, “0” to unset it.
flag_draft body integer Message has not completed composition (marked as a draft). Set this parameter to “1” to set the flag, “0” to unset it.
{
  "success": true
}

Listing folders

List folders for a given source (email address).

HTTP request

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

Required parameters

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

Optional parameters

Name Location Type Description
include_extended_counts query integer 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.
no_cache query integer 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.

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

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

Optional parameters

Name Location Type Description
delim query string 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.
include_extended_counts query integer 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.
{
  "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 perform 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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
callback_url body string (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.

Optional parameters

Name Location Type Description
filter_to body string Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from body string Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_cc body string Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subject body string Check for new messages with a subject matching a given string or regular expression
filter_thread body string 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.
filter_file_name body string 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.
filter_folder_added body string 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.
filter_folder_removed body string 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.
filter_to_domain body string Check for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domain body string Check for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_body body integer Set to “1” to include message bodies in the result.
body_type body string 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”.
include_header body integer set to “1” or “raw” to include message headers in the result.
receive_all_changes body integer 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.
receive_drafts body integer Set to “1”, you will receive messages that are flagged as “\Drafts” in Gmail.

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
webhook_id url integer Unique id of a user-level webhook.

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
webhook_id url string Unique id of a user level webhook.

Optional parameters

Name Location Type Description
callback_url body string (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.
active body integer 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.
filter_to body string Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from body string Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_cc body string Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subject body string Check for new messages with a subject matching a given string or regular expression
filter_thread body string 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.
filter_file_name body string 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.
filter_folder_added body string 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.
filter_folder_removed body string 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.
filter_to_domain body string Check for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domain body string Check for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_body body integer Set to “1” to include message bodies in the result.
body_type body string 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”.
include_header body integer set to “1” or “raw” to include message headers in the result.
receive_all_changes body integer 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.
receive_drafts body integer Set to “1”, you will receive messages that are flagged as “\Drafts” in Gmail.

Delete a specific user level webhook

HTTP Request

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

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
webhook_id url string Unique id of a user-level webhook.

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",
    "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
}

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

Name Location Type Description
callback_url body string (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.

Optional parameters

Name Location Type Description
active body integer 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.
filter_to body string Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from body string Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_cc body string Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subject body string Check for new messages with a subject matching a given string or regular expression
filter_thread body string 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.
filter_file_name body string 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.
filter_folder_added body string 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.
filter_folder_removed body string 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.
filter_to_domain body string Check for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domain body string Check for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_body body integer Set to “1” to include message bodies in the result.
body_type body string 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”.
include_header body integer set to “1” or “raw” to include message headers in the result.
receive_all_changes body integer 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.
receive_drafts body integer Set to “1”, you will receive messages that are flagged as “\Drafts” in Gmail.
receive_historical body integer 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.

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.

HTTP Request

GET 2.0/webhooks

Required parameters

Name Location Type Description
webhook_id url string Unique id of an application level webhook

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

Name Location Type Description
webhook_id url string Unique id of an application level webhook

Optional parameters

Name Location Type Description
active body integer 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.
filter_to body string Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from body string Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_cc body string Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subject body string Check for new messages with a subject matching a given string or regular expression
filter_thread body string 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.
filter_file_name body string 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.
filter_folder_added body string 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.
filter_folder_removed body string 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.
filter_to_domain body string Check for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domain body string Check for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_body body integer Set to “1” to include message bodies in the result.
body_type body string 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”.
include_header body integer set to “1” or “raw” to include message headers in the result.
receive_all_changes body integer 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.
receive_drafts body integer Set to “1”, you will receive messages that are flagged as “\Drafts” in Gmail.
receive_historical body integer 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.

Delete a specific application level webhook

Delete an existing application level webhook.

HTTP Request

DELETE 2.0/webhooks/:webhook_id

Required parameters

Name Location Type Description
webhook_id url string Unique id of an application level webhook

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",
    "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.

Sample PHP code for authenticating a postback

<?php
// decode request body
$body = json_decode(file_get_contents('php://input'), true);

if ($body['signature'] == hash_hmac('sha256', $body['timestamp'].$body['token'], YOUR_CONTEXTIO_CONSUMER_SECRET)) {  
  // request is authenticated
}
else {  
  // invalid request, you can ignore it
}

Sample Golang code for authenticating a postback

// create the auth token
tok := append(token, []byte(strconv.Itoa(timestamp))...)
mac := hmac.New(sha256.New, []byte(secret))
_, err := mac.Write([]byte(tok))
if err != nil {
  return false, errors.Wrap(err, "writing token to signature")
}

return mac.Sum(nil) == signature, nil

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": "<12345_abcde@email.com>",
    "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"
      }
    },
    "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

Name Location Type Description
id url string Unique id of an account accessible through your API key.

Optional parameters

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

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
email url string Email address of a contact.

List files shared with a specific contact(s)

HTTP Request

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

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
email url string Email address of a contact.

Optional parameters

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

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
email url string Email address of a contact.

Optional parameters

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

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
email url string Email address of a contact.

Optional parameters

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

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
    }

Note: sent_from_account_count is the number of messages that include the contact in the To, CC, or BCC fields of an email from a source of the account.

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"
  ]
}

Note: sent_from_account_count is the number of messages that include the contact in the To, CC, or BCC fields of an email from a source of the account.

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

Name Location Type Description
id url string Unique id of an account accessible through your API key.

Optional parameters

Name Location Type Description
file_name query string 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”
file_size_min query integer query
file_size_max query integer Search for files based on their size (in bytes).
email query string Email address of the contact for whom you want the latest files in which this email address was listed as a recipient.
to query string Email address of a contact files have been sent to.
from query string Email address of a contact files have been received from.
cc query string Email address of a contact CC'ed on the messages.
bcc query string Email address of a contact BCC'ed on the messages.
date_before query integer (Unix timestamp) 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.
date_after query integer (Unix timestamp) 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.
indexed_before query integer (Unix timestamp) 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.
indexed_after query integer (Unix timestamp) 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.
source query string Filter messages by the account source label.
sort_order query string The sort order of the returned results. Possible values are “asc” and “desc”.
limit query integer The maximum number of results to return. The maximum per call is 100.
offset query integer Start the list at this offset (zero-based).

Get details about a specific file

HTTP Request

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

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
file_id url string Unique id of a file.

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 extension 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

Name Location Type Description
id url string Unique id of an account accessible through your API key.
file_id url string Unique id of a file.

Optional parameters

Name Location Type Description
as_link query integer Set to “1”, get an AWS link you can use to download the file.

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 disconnection 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

Required parameters

Name Location Type Description
id url string Unique id of an account accessible through your API key.
label url string The label property of the email account instance.

Optional parameters

Name Location Type Description
status_callback_url body string (url) If specified, we’ll make a POST request to this URL if the connection status of the email account changes.
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 app/status_callback_url

Optional parameters

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

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

Name Location Type Description
email query string An email address you want to discover IMAP settings for. Make sure source_type is set to “IMAP”.
{
  "email": "danascully@email.com",
  "found": true,
  "resource_url": "https://api.context.io/lite/discovery",
  "type": "generic",
  "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 application 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

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

Get information about an oauth provider

“GET 2.0/oauth_providers/:key”

Required parameters

Name Location Type Description
key url string The consumer key for this external OAuth provider.

Delete an oauth provider

“DELETE 2.0/oauth_providers/:key”

Required parameters

Name Location Type Description
key url string The consumer key for this external OAuth provider.
  {
    "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

Listing users

HTTP request

GET lite/users

Optional parameters

Name Location Type Description
email query string The primary email address used to receive emails in this user.
status query string Only return users with email accounts with the specified status. If a user has many email accounts, only those matching the given value will be included in the response. Possible statuses are: “INVALID_CREDENTIALS”, “CONNECTION_IMPOSSIBLE”, “OK”, “TEMP_DISABLED” and “DISABLED”.
status_ok query integer Set to “0” to get sources that are not working correctly. Set to “1” to get those that are.
limit query integer The maximum number of results to return. The maximum limit is “100”.
offset query integer Start the list at this offset (zero-based).

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

Name Location Type Description
email body string The primary email address used to receive emails in this user.
server body string Name of IP of the IMAP server, eg. imap.email.com. Required when creating an email account and user in a single call.
username body string The username used to authenticate an IMAP connection. On some servers, this is the same thing as the primary email address.
use_ssl body integer 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 an email account and user in a single call.
port body integer Port number to connect to on the server. For most servers, SSL is 993, and unencrypted (non-SSL) is 143. Required when creating an email account and user in a single call.
type body string Currently, the only supported type is IMAP. Required when creating an email account and user in a single call.
password body string Password for this email account. Required when creating an email account and user in a single call. Ignored if any of the provider_* parameters are set below.
provider_refresh_token body string An OAuth2 refresh token obtained from the IMAP user provider to authenticate this email user. Required if using oauth when creating an email account and user in a single call.
provider_consumer_key body string The OAuth2 Client ID used to obtain the the refresh token for the above user. Required if using oauth when creating an email account and user in a single call. That consumer key and secret must be configured in your Context.IO user, see oauth_providers

Optional parameters

Name Location Type Description
migrate_account_id body string Existing 2.0 account_id you want to migrate to Lite. This is the only needed parameter when migrating an account to Lite.
first_name body string First name of the user holder.
last_name body string Last name of the user holder.
status_callback_url body string (url) If specified, we’ll make a POST request to this URL if the connection status of the email account changes.
{
  "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 an email account to an existing user. A user id is required to add an email account to an existing user.

HTTP request

POST lite/users/:id/email_accounts

Required parameters

Name Location Type Description
id body integer Unique id of a user accessible through your API key.
email body string The primary email address used to receive emails for this user.
server body string Name of IP of the IMAP server, eg. imap.email.com. Required when creating an email account and user in a single call.
username body string The username used to authenticate an IMAP connection. On some servers, this is the same thing as the primary email address.
use_ssl body integer 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 an email account and user in a single call.
port body integer Port number to connect to on the server. For most servers, SSL is 993, and unencrypted (non-SSL) is 143. Required when creating an email account and user in a single call.
type body string Currently, the only supported type is IMAP. Required when creating an email account and user in a single call.

Optional parameters

Name Location Type Description
status_callback_url body string (url) If specified, we’ll make a POST request to this URL if the connection status of the email_account changes.
password body string Password for this email account. Required when creating an email account and user in a single call. Ignored if any of the provider_* parameters are set below.
provider_refresh_token body string An OAuth2 refresh token obtained from the IMAP user provider to authenticate this email user. Required if using oauth when creating an email account and user in a single call.
provider_consumer_key body string The OAuth2 Client ID used to obtain the the refresh token for the above user. Required if using oauth when creating an email account and user in a single call. That consumer key and secret must be configured in your Context.IO user, see oauth_providers
{
  "success": true,
  "label": "foxmulder::email",
  "resource_url": "https://api.context.io/lite/users/55555aaaaa66666bbbbb7777/email_accounts/foxmulder%3A%3Aemail",
  "emailAccountId": "foxmulder::email"
}

Delete a user or email account

If you need to delete a user, you can do so by sending a DELETE request to the user instance endpoint. This will delete the user and all email accounts associated with it.

HTTP request

DELETE lite/users/:id/

{
  "success": true
}

If you wish to only delete a certain email account from the user, but do not delete the user itself, you can send a DELETE request to the email_account label instance endpoint.

HTTP request

DELETE lite/users/:id/email_accounts/:label

{
  "success": true
}

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

Name Location Type Description
callback_url body string (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.

Optional parameters

Name Location Type Description
email body string (url) 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.
first_name body string First name of the user holder.
last_name body string Last name of the user holder.
status_callback_url body string (url) If specified, we’ll make a POST request to this URL if the connection status of the email account changes.
{
  "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

Name Location Type Description
token url string The unique random token used for the graphical user creation process

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 all connect tokens

HTTP request

GET lite/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

Name Location Type Description
id url string Unique id of a user accessible through your API key.

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

Name Location Type Description
id url string Unique id of a user accessible through your API key.
label url string The label property of the email account instance.
  {
    "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

Name Location Type Description
id url string Unique id of a user accessible through your API key.
{
  "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

Name Location Type Description
id url string Unique id of a user accessible through your API key.

Optional parameters

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

Getting details of a specific email account

The name of an 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

Name Location Type Description
id url string Unique id of a user accessible through your API key.
label url string The label property of the email account instance.
 {
    "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

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

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

Name Location Type Description
id url string Unique id of a user accessible through your API key.
label url string The label property of the email account instance. You can use 0 as an alias for the first email account of a user.
folder url string The full folder path using / as the path hierarchy delimiter.
{
    "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

Name Location Type Description
delimiter query string 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 parameter to tell us what you’re using.

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

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

Optional parameters

Name Location Type Description
delimiter query string 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.
include_body query integer 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.
include_headers query mixed 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.
include_flags query integer 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.
body_type query string Used when include_body is set to get only body parts of a given MIME-type (for example text/html)
limit query integer The maximum number of results to return. The maximum limit is “100”. The default if no limit is provided is “25”.
offset query integer Start the list at this offset (zero-based).

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

Name Location Type Description
id url string Unique id of a user accessible through your API key.
label url string The label property of the email account instance.
folder url string The full folder path using / as the path hierarchy delimiter.
message_id url string 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.

Optional parameters

Name Location Type Description
delimiter query string 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.
include_body query integer 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.
body_search_string query string Searches the folder for message bodies containing this string. The search is case insensitive.
include_headers query integer 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.
include_flags query integer 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.
body_type query string Used when include_body is set to get only body parts of a given MIME-type (for example text/html)
{
  "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

Name Location Type Description
id url string Unique id of a user accessible through your API key.
label url string The label property of the email account instance.
folder url string The full folder path using / as the path hierarchy delimiter.
message_id url string 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.

Optional parameters

Name Location Type Description
delimiter query string 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.
  {
    "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

Name Location Type Description
id url string Unique id of a user accessible through your API key.
label url string The label property of the email account instance.
folder url string The full folder path using / as the path hierarchy delimiter.
message_id url string 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.
attachment_id url string The index of the file attachment.

Optional parameters

Name Location Type Description
delimiter query string 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.

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

Name Location Type Description
delimiter query string 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.
type query string Used when include_body is set to get only body parts of a given MIME-type (for example text/html).

Get message flags

HTTP request

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

Optional parameters

Name Location Type Description
delimiter query string 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.
{
  "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

Name Location Type Description
delimiter query string 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.
raw query integer By default, this returns messages headers parsed into an object. Set this parameter to “1” to get raw unparsed headers.
{
  "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

Name Location Type Description
delimiter query string 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.

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

Name Location Type Description
delimiter body string 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.

Mark the message as unread

HTTP request

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

Optional parameters

Name Location Type Description
delimiter body string 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.
{
"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

Name Location Type Description
new_folder_id query string Specifies the destination folder for the message move.

Optional parameters

Name Location Type Description
delimiter query string 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.
{
  "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 perform 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

Name Location Type Description
id url string Unique id of a user accessible through your API key
callback_url body string 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.

Optional parameters

Name Location Type Description
filter_to body string Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from body string Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_cc body string Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subject body string Check for new messages with a subject matching a given string or regular expression
filter_thread body string 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.
filter_file_name body string 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.
filter_folder_added body string 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.
filter_to_domain body string Check for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domain body string Check for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_body body integer Set to “1” to include message bodies in the result.
body_type body string 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”.
include_header body mixed Set to “1” or “raw” to include message headers in the result.
receive_all_changes body integer 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.
receive_drafts body integer Set to “1”, you will receive messages that are flagged as “\Drafts” in Gmail

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

Name Location Type Description
id url string Unique id of a user accessible through your API key

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

Name Location Type Description
id url string Unique id of a user accessible through your API key
webhook_id url string Unique id of a user level webhook

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

Name Location Type Description
id url string Unique id of a user accessible through your API key
webhook_id url string Unique id of a user level webhook

Optional parameters

Name Location Type Description
callback_url body string 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.
active body integer 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.
filter_to body string Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from body string Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_cc body string Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subject body string Check for new messages with a subject matching a given string or regular expression
filter_thread body string 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.
filter_file_name body string 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.
filter_folder_added body string 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.
filter_to_domain body string Check for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domain body string Check for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_body body integer Set to “1” to include message bodies in the result.
body_type body string 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”.
include_header body mixed set to “1” or “raw” to include message headers in the result.
receive_all_changes body integer 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.
receive_drafts body integer Set to “1”, you will receive messages that are flagged as “\Drafts” in Gmail

Delete a specific user level webhook

HTTP Request

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

Required parameters

Name Location Type Description
id url string Unique id of a user accessible through your API key
webhook_id url string 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 lite/webhooks

Required parameters

Name Location Type Description
callback_url body string 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.

Optional parameters

Name Location Type Description
active body integer 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.
filter_to body string Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from body string Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_cc body string Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subject body string Check for new messages with a subject matching a given string or regular expression
filter_thread body string 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.
filter_file_name body string 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.
filter_folder_added body string 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.
filter_to_domain body string Check for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domain body string Check for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_body body integer Set to “1” to include message bodies in the result.
body_type body string 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”.
include_header body mixed set to “1” or “raw” to include message headers in the result.
receive_all_changes body integer 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.
receive_drafts body integer Set to “1”, you will receive messages that are flagged as “\Drafts” in Gmail
receive_historical body integer 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.

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

Name Location Type Description
webhook_id url string Unique id of an application level webhook

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

Name Location Type Description
webhook_id url string Unique id of an application level webhook

Optional parameters

Name Location Type Description
active body integer 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.
filter_to body string Check for new messages received to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_from body string Check for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_cc body string Check for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subject body string Check for new messages with a subject matching a given string or regular expression
filter_thread body string 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.
filter_file_name body string 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.
filter_folder_added body string 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.
filter_to_domain body string Check for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domain body string Check for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_body body integer Set to “1” to include message bodies in the result.
body_type body string 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”.
include_header body mixed set to “1” or “raw” to include message headers in the result.
receive_all_changes body integer 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.
receive_drafts body integer Set to “1”, you will receive messages that are flagged as “\Drafts” in Gmail
receive_historical body integer 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.

Delete a specific application level webhook

Delete an existing application level webhook.

HTTP Request

DELETE lite/webhooks/:webhook_id

Required parameters

Name Location Type Description
webhook_id url string Unique id of an application level webhook

Webhook created response

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

Webhook details response

  {
    "callback_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.

Sample PHP code for authenticating a postback

<?php
// decode request body
$body = json_decode(file_get_contents('php://input'), true);

if ($body['signature'] == hash_hmac('sha256', $body['timestamp'].$body['token'], YOUR_CONTEXTIO_CONSUMER_SECRET)) {  
  // request is authenticated
}
else {  
  // invalid request, you can ignore it
}

Sample Golang code for authenticating a postback

// create the auth token
tok := append(token, []byte(strconv.Itoa(timestamp))...)
mac := hmac.New(sha256.New, []byte(secret))
_, err := mac.Write([]byte(tok))
if err != nil {
  return false, errors.Wrap(err, "writing token to signature")
}

return mac.Sum(nil) == signature, nil

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": "<12345_abcde@email.com>",
    "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"
      }
    },
    "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 an 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 disconnection 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 an 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 an 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 an 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

Required parameters

Name Location Type Description
id url string Unique id of a user accessible through your API key
label url string The label property of the email account instance.

Optional parameters

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

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 app/status_callback_url

Optional parameters

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

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

Name Location Type Description
email query string An email address you want to discover IMAP settings for. Make sure email account_type is set to “IMAP”.
{
  "email": "danascully@email.com",
  "found": true,
  "resource_url": "https://api.context.io/lite/discovery",
  "type": "generic",
  "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 application 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

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

Get information about an oauth provider

“GET lite/oauth_providers/:key”

Required parameters

Name Location Type Description
key url string The consumer key for this external OAuth provider

Delete an oauth provider

“DELETE lite/oauth_providers/:key”

Required parameters

Name Location Type Description
key url string The consumer key for this external OAuth provider
  {
    "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"
  }

App 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

Name Location Type Description
status_callback_url body 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

Name Location Type Description
account query Only include logs of webhooks from the specified account id string
webhook_id query Only include logs of webhooks with the specified webhook id string
timestamp_before query Only include logs of webhooks before a given timestamp. integer (Unix timestamp)
timestamp_after query Only include logs of webhooks after a given timestamp. integer (Unix timestamp)
status_code_from query Only return webhook logs where the status code is greater than the number specified. For example 200) integer
status_code_to query 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

Name Location Type Description
account query Only include logs of webhooks from the specified account id string
timestamp_before query Only include logs of calls before a given timestamp. integer (Unix timestamp)
timestamp_after query Only include logs of calls after a given timestamp. integer (Unix timestamp)
status_code_from query Only return logs of calls where the status code is greater than the number specified. For example 200) integer
status_code_to query Only return logs of call where the status code is less than the number specified. For example 500) integer
request_method query Only return logs of calls where the http method is the one specified. For example, GET string
request_path query 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, you’re using a wrong parameter, or passing 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 vice-versa)
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 exceeding 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 temporarily offline for maintenance. 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 publicly 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 will need to figure out how to best make calls against the API.

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: