NAV Navbar

Getting started

What you need before you start:

Choosing an API version

The 2.0 version of the API is DEPRECATED. Developers using this version should contact support for help with your migration plan.

We are currently merging all API functionality that does not require the 2.0 caching layer into one, unified API, under the Lite version umbrella.

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: “OK” 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"
  }
 }

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: “OK” 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.

Create a folder

Create a new folder for an email account.

HTTP request

POST 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.

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 create, you’re free to use what you want, just make sure you set this delimiter parameter to tell us what you’re using.

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 (optionally) folder to list messages for.

HTTP request

GET lite/users/:id/email_accounts/:label/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.
subject query string Get messages whose subject matches this search string.
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.
date_before query integer (Unix timestamp) Only include messages on or 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 on or 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.
include_body query integer Set to “1” to include message bodies in the result.
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.
include_flags query integer Set to “1” to include IMAP flags of messages in the result.
sort_order query string The sort order of the returned results. Possible values are “asc” and “desc”
body_search_string query string Searches the folder for message bodies containing this string. The search is case insensitive.
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).

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.
subject query string Get messages whose subject matches this search string.
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.
date_before query integer (Unix timestamp) Only include messages on or 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 on or 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.
include_body query integer Set to “1” to include message bodies in the result.
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.
include_flags query integer Set to “1” to include IMAP flags of messages in the result.
sort_order query string The sort order of the returned results. Possible values are “asc” and “desc”
body_search_string query string Searches the folder for message bodies containing this string. The search is case insensitive.
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”.

“message_id”: This is a Context.IO generated ID that will be unique.

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 “gmail_message_id” property of the message.

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.
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.
include_flags query integer Set to “1” to include IMAP flags for this message in the result.
body_type query string Used when include_body is set to get only body parts of a given MIME-type (for example text/html)

GET lite/users/:id/email_accounts/:label/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.
message_id url string Unique id of a message. This can be the “message_id” or “gmail_message_id” property of the message.

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.
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.
include_flags query integer Set to “1” to include IMAP flags for this message in the result.
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",
  "message_id": "aaaa11110000lll1",
  "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 “gmail_message_id” property of the message.

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 “gmail_message_id” property of the message.
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.
as_link query integer Set to “1”, get an AWS link you can use to download the file.

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.

Listing contacts (beta)

Contacts endpoints are in beta. If you are interested in using these endpoints, please contact support to opt in.

This call allows you to list a users’ contacts along with a ‘heat map’-style count of how often the user has interacted with that contact. TotalCount counts the number of times the user has seen messages from that contact. IndirectCount counts the number of times a user has recieved messages from that contact. DirectCount counts the number of times a user has recieved a message from a contact and has replied to that message. Please note that these counts do not account for deleted messages and do not reflect the current state of the mailbox.

HTTP request

GET lite/users/:id/contacts

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
limit query integer By default, this returns 100 contacts. Set this parameter to less than 100 to get fewer contacts in a single return.
offset query interger Specifies the offset for a list of contacts, enables you to page through a user with over 100 contacts
sort_order query string Default is desc aka descending order, based on the total_count field. Set this to asc to see contacts with the lowest total_count first.
sort_by query string Default is total_count. You can also sort by direct_count and indirect_count.
{
  "contacts": [
    {
      "email": "username@example.com",
      "total_count": 121,
      "direct_count": 0,
      "indirect_count": 121,
      "name": "User Name",
      "last_received": 1514764800,
      "cio_user_id": "<userid>",
      "contact_id": "ZXhhbXBsZUBlbWFpbC5jb20"
    },
    {
      "email": "username@otherexample.com",
      "total_count": 110,
      "direct_count": 100,
      "indirect_count": 10,
      "name": "Other User Name",
      "last_received": 1514764800,
      "cio_user_id": "<userid>",
      "contact_id": "ZXhhbXBsZUBleGFtcGxlLmNvbQ"
    }
  ]
}

Getting a single contact (beta)

Contacts endpoints are in beta. If you are interested in using these endpoints, please contact support to opt in.

This call returns information for a single contact

HTTP request

GET lite/users/:id/contacts/:contactid

Required parameters

Name Location Type Description
id url string Unique id of a user accessible through your API key.
contactid url string Unique id of a users’ contact.
{
  "email": "someone@example.com",
  "total_count": 139,
  "direct_count": 0,
  "indirect_count": 139,
  "name": "Some One",
  "last_received": 1514764800,
  "cio_user_id": "<userid>",
  "contact_id": "ZXhhbXBsZUBlbWFpbC5jb20"
}

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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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 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_search body string Check for new messages where a the text of the body matches the given string. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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
active body integer By default, webhooks are set to active when first created. When editing, this defaults to “1”. Set to “0” to stop receiving callbacks for this webhook.
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.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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 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_search body string Check for new messages where a the text of the body matches the given string. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. When editing, this defaults to “1”. Set to “0” to stop receiving callbacks for this webhook.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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 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_search body string Check for new messages where a the text of the body matches the given string. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. When editing, this defaults to “1”. Set to “0” to stop receiving callbacks for this webhook.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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 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_search body string Check for new messages where a the text of the body matches the given string. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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, err
}

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

Discovery endpoints will 404 if no configuration is found. This doesn’t mean that we can’t connect to that account, just that we don’t know what connection parameters to use. You can still provide those parameters yourself.

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

Optional parameters

Name Location Type Description
list query integer Set to 1 to get a list of all available settings.
{
  "email": "danascully@email.com",
  "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”.

Yahoo and AOL While Yahoo and AOL support oauth access to IMAP, they do not make API keys with access to the Mail scope publicly accessible. If you already have a Yahoo or AOL API key with access to the Mail scope, Context.IO will support that. Simply add them as an Oauth Provider via the API endpoints below, or by using the developer console here.

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

2.0 API (DEPRECATED)

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: “OK” 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 first source of an account. To get message from any other source you must include the optional source parameter in the request.

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.
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.
date_before query integer (Unix timestamp) or string format mm/dd/yyyy Only include messages on or 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) or string format mm/dd/yyyy Only include messages on or 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.
include_body query integer Set to “1” to include message bodies in the result.
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.
include_flags query integer Set to “1” to include IMAP flags of messages in the result.
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.
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”).

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
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.
subject query string Get messages whose subject matches this search string.
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.
date_before query integer (Unix timestamp) Only include messages on or 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 on or 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.
include_body query integer Set to “1” to include message bodies in the result.
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.
include_flags query integer Set to “1” to include IMAP flags of messages in the result.
sort_order query string The sort order of the returned results. Possible values are “asc” and “desc”
body_search_string query string Searches the folder for message bodies containing this string. The search is case insensitive.
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).

Get an individual message

Get an individual message based on a “message_id”.

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” returned by Webhooks or the API.

Optional parameters

Name Location Type Description
include_body query integer Set to “1” to include the message body in the result.
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.
include_flags query integer Set to “1” to include IMAP flags for this message in the result.
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.
 {
  "date": 1234567890,
  "date_received": 1234567890,
  "date_indexed": null,
  "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": "aaaa11110000lll1",
  "list_headers": [ ],
  "in_reply_to": null,
  "references": [ ],
  "files": [
    {
      "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"
    }
  ],
  "body": [
    {
      "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"
  ],
  "sources": [
      {
        "label": "foxmulder::email",
        "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/sources/foxmulder%3A%email"
      }
    ]
  "resource_url": "https://api.context.io/2.0/accounts/55555aaaaa66666bbbbb7777/messages/aaaa11110000lll1"
}

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” returned by Webhooks or the API.
{
    "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” returned by Webhooks or the API.
{
  "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” returned by Webhooks or the API.

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” returned by Webhooks or the API.
  {
    "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” returned by Webhooks or the API.

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” returned by Webhooks or the API.
RAW RFC-882 source message

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 a message. This can be the “message_id” returned by Webhooks or the API.
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).

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).
{
  "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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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_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_search body string Check for new messages where a the text of the body matches the given string. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. Expect a message_type to be returned with created or updated when this param is set.
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
active body integer By default, webhooks are set to active when first created. When editing, this defaults to “1”. Set to “0” to stop receiving callbacks for this webhook.
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.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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_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_search body string Check for new messages where a the text of the body matches the given string. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. Expect a message_type to be returned with created or updated when this param is set.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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_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_search body string Check for new messages where a the text of the body matches the given string. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. Expect a message_type to be returned with created or updated when this param is set.
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. When editing, this defaults to “1”. Set to “0” to stop receiving callbacks for this webhook.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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_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_search body string Check for new messages where a the text of the body matches the given string. You can filter names using typical shell wildcards such as [], ?, and * or regular expressions by enclosing the search expression in a leading / and trailing /.
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. Expect a message_type to be returned with created or updated when this param is set.
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, err
}

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

Working with files or attachments

Get information about files and download content.

List all files for a messages

Get a list of files in a message.

HTTP Request

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

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” returned by Webhooks or the API.

Download a file’s contents

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

HTTP Request

GET 2.0/accounts/:id/messages/:message_id/files/:file_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” returned by Webhooks or the API.
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.

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/messages/:message_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.

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.

Discovery endpoints will 404 if no configuration is found. This doesn’t mean that we can’t connect to that account, just that we don’t know what connection parameters to use. You can still provide those parameters yourself.

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

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 is a provisional account / trial period account?

A provisional account is a Context.IO developer account that is only active for 90 days by default. After 90 days, the provisional account will be deleted unless you follow the instructions below to remove the provisional status.

We believe 90 days will be enough for developers to review the API and determine whether it will be a good fit for their needs.

What are the limits of a provisional account?

During your provisional period, you can only have up to 25 users, and make 500 calls to the API per hour.

This should be enough for developers reviewing the API. A provisional account is not meant for active development on a production-level application.

Can you increase my call limit during the trial period?

No, the call limit during the trial period cannot be lifted. If you feel 500 calls per hour are not enough for your app, we highly recommend you heavily use webhooks for consuming data, as opposed to making calls against the API repeatedly. Our API is meant to be used primarily via webhooks.

How do I remove the provisional status of my developer account to extend use beyond 90 days?

In order to remove the provisional status of your account and extend your usage period beyond the initial 90 days, Context.IO must review your API usage.

Context.IO will perform a call analysis of your account to ensure you are following development best practices (below are the best practices we look for).

When you are ready for us to review your usage of the API, you can reach out to us via email.

What are the best practices I must follow in order to lift the provisional status of my account?

Context.IO is meant to be primarily used via webhooks. Best practices we recommend are:

  1. DO: Consume data primarily via webhooks. Set-up webhooks to be notified of new messages arriving in a mailbox instead of constantly polling the API for new messages.

  2. DO: Use historical webhooks for message backscans. If your application requires historical data (i.e. messages dating back to the beginning of a mailbox history), you will need to setup your webhooks to receive historical messages.

  3. DO: Store account IDs / user IDs on your end. You should store the Context.IO unique account / user ID on your end, so you are able to retrieve data for your end-users without having to poll Context.IO for a user ID.

  4. DO: Store message IDs on your end. You should also store message IDs of messages you care about, in case you would need to retrieve it later. (We highly recommend you do store the messages you care about on your end.)

  5. DO: Clearly state in your privacy policy that you use Context.IO as follows:

This application is built using Context.IO technology. By signing up or using this application, you understand and agree that DokDok, Inc., its parent company, Return Path, Inc. and their affiliates (collectively “Context.IO Providers”), who provide Context.IO, will have access to your information and will be permitted to use that information in accordance with Return Path’s Privacy Policy. If you wish to opt out of sharing your information with Context.IO Providers, you may do so at optout.context.io.
  1. DON’T: use Context.IO to populate a live feed. You should not make calls to Context.IO to populate your application’s live feed / display of messages. You should populate your applications’ feed from information from your database, and you should populate your database from webhooks you consume via Context.IO. Why? Each call to Context.IO that requests messages is a call against IMAP, and IMAP can be unpredictable. This is why we recommend you use the API asynchronously via webhooks, so we can maintain the IMAP connection for you and proactively send you the data you need. Otherwise, we cannot ensure calls to retrieve messages straight from IMAP will be performant.

How much does Context.IO cost during the trial period?

There is no cost to you during the trial period.

How much will I pay after my trial period?

You can use Context.IO for free after your trial period has ended in exchange for anonymous, aggregated data sharing. If you want to learn more about how we use data sharing, you can read our privacy FAQ.

Individual users can opt-out of data sharing at any time using our opt-out page, and in such cases, there is no cost to you. In fact, we require all developers using the API for free in our data sharing option to include a link to our opt-out page in their Privacy Policy.

If you wish to fully opt-out of data sharing altogether for your entire user base, you can review our pricing options on our pricing page.

If Context.IO is not for me, what happens to my account after 90 days?

After the 90-day period is over, you developer account will be deleted, along with any users and webhooks under your developer key.

In other words, if Context.IO is not for you, you can simply stop using Context.IO, and we will remove all information associated with your account after 90 days — you won’t even have to contact us to delete your account.

Do I get to keep my key and secret after my account is no longer a provisional account?

Your key and secret remain the same from the moment you sign up for Context.IO. Your secret will remain the same unless you generate a new one. Context.IO does not change API keys or secrets.

What are your API rate limits?

Provisional account limits

For new developers in the provisional / trial period of the API, we limit users to 25 users, and calls to the API to 500 calls per hour. These limits are lifted once an account’s provisional status is lifted.

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.

Why can’t I access the Sent folder?

In order to remain compliant with international privacy laws, Context.IO does not sync outgoing messages from end-users’ Sent folder(s), starting on February 1st, 2018.

You can read more about this change here.

How do I sign API requests?

We recommend you use one of our client libraries, as they handle API signing for you. You can find our client libraries here. If we do not have a client library in the language of your choice, we recommend looking for a library or plugin in your preferred language that will handle API request signatures for you. Most REST libraries will allow you to add Authorization headers or will generate the signature for you.

If you require further help signing requests, please read this support article from our knowledge base.

What do I need to do to be GDPR compliant?

  1. Use the required privacy policy wording. This should appear for all of your users.

  2. Show a Just In Time (JIT) notification for EU users allowing them to opt-in to data share.

What is the exact wording I should include in my Privacy Policy?

As a developer using Context.IO, you are required to state you use Context.IO in your application’s Privacy Policy. This must be a publicly available link.

The exact wording you should use is:

This application is built using Context.IO technology. By signing up or using this application, you understand and agree that DokDok, Inc., its parent company, Return Path, Inc. and their affiliates (collectively “Context.IO Providers”), who provide Context.IO, will have access to your information and will be permitted to use that information in accordance with Return Path’s Privacy Policy. If you wish to opt out of sharing your information with Context.IO Providers, you may do so at optout.context.io.

What is a JIT notification and what does it need to say?

A JIT (Just In Time) notification is a type of notification shown to users when they need to take action on something.

We require devs using Context.IO to show a JIT notification to users in the EU, letting them know about Context.IO, and allowing them to opt-in to data sharing.

The exact wording you should use is:

This application is built using Context.IO (Return Path, Inc.) technology. Return Path, Inc. collects and shares information about non-personal email messages (e.g., commercial emails), including data about your email habits. Your personal data will be de-identified or pseudonymized, then aggregated, and will be used to help Return Path improve upon their existing and/or new Services, as well as helping their clients with email delivery optimization and best practices, spam filtering, and detecting and preventing phishing attacks.
Please read the Return Path Privacy Policy to understand the specifics of what data is collected and how it will be used. You can withdraw your consent at any time by disconnecting this application from your inbox.
__ I agree to the collection, use, and processing of my personal data as outlined in the Return Path Privacy Policy.
By clicking “Let’s Go”, you accept our Terms of Use. Our business depends on the trust of millions of people like you. If you have any questions, please let us know.
LET’S GO!

If you wish to change the wording, you must run the changes by support@context.io.

What if I don’t want to show a JIT to my EU users?

If you do not want to show the JIT to your EU users, you have the following options:

  1. Do not use Context.IO with users in the EU: If you have users in the EU, you are required to show them the JIT notification as we have outlined. You can choose not to support users in the EU, or not use Context.IO for your users in the EU.
  2. Pay to opt-out of data share: Context.IO is free to use for developers who agree to data share. If you do not wish to data share, you can find a pricing plan that works for you and opt-out your entire user base from data sharing.

I don’t have users in the EU / don’t plan on supporting EU users. Do I need to be GDPR compliant?

First, we strongly recommend all developers using our API determine the location of their end-users, regardless if you want to make your app available to EU users or not. Using IP addresses are usually a good way of determining user location.

Next, if you do not plan on complying with GDPR regulations, you need to check user location to prevent EU users from signing up. This will ensure you are not subject to fines for breaking GDPR laws. As an added layer of protection, we have a setting to help with this task.

You can contact us via support@context.io, and we will turn on a feature that will disable new EU signups for you.

This will automatically block any EU users from signing up to your service. Please note: This setting will not remove EU users that already signed up. The setting only blocks new sign ups.

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:

Do you support 3-legged authentication?

We do not support 3-legged authentication with Context.IO.

If you have a mobile app that you wish to integrate with Context.IO, we recommend setting up a proxy server that can make requests to Context.IO on behalf of your application.

Do you have SDKs for iOS or Android for Context.IO?

We do not have SDKs for iOS or Android at this time.

For Android, we recommend a REST library like Retrofit.

For iOS, we recommend Siesta