API version:
  • 2.0
  • Lite
  • Which Should I Use?

accounts/webhooks

Supported methods

List methods:GETPOST

Instance methods:GETDELETEPOST

Webhooks list

GET: Listing of WebHook configured for an account

GET https://api.context.io/2.0/accounts/id/webhookstest it
idUnique id of an account accessible through your API key

Response body

[
  {
    "callback_url": stringYour callback URL to which we'll POST message data,
    "failure_notif_url": stringYour callback URL for failure notifications,
    "active": booleanWhether this webhook is currently applied to new messages we find in the account or not,
    "failure": booleantrue means we're having issues connecting to the account and gave up after a couple retries. The failure_notif_url is called when a webhook's failure property becomes true.,
    "webhook_id": stringId of the webhook,
    filter_*: stringValue of a filter assigned to this webhook when created,
    ...
  },
  ...
]

POST: Create a new WebHook on an account

POST https://api.context.io/2.0/accounts/id/webhookstest it
idUnique id of an account accessible through your API key

Parameters

nametypedescription
required:
callback_urlstring
(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.
failure_notif_urlstring
(url)
A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can't re-establish it.

The callback URL is called with an HTTP POST with more information in request body, see receiving failure notifications.
optional:
filter_tostringCheck for new messages sent to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_fromstringCheck for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_ccstringCheck for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subjectstringCheck for new messages with a subject matching a given string or regular expresion
filter_threadstringCheck for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id or message_id of an existing message currently in the thread.
filter_new_importantstringCheck for new messages automatically tagged as important by the Gmail Priority Inbox algorithm.

To trace all messages marked as important (including those manually set by the user), use filter_folder_added with value \Important. Note the leading back-slash character in the value, it is required to keep this specific to Gmail Priority Inbox. Otherwise any message placed in a folder called "Important" would trigger the WebHook.
filter_file_namestringCheck 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_addedstringCheck for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track.
filter_folder_removedstringCheck for messages removed from a given folder. On Gmail, this is equivalent to having a label removed from a message. The value should be the complete name (including parents if applicable) of the folder you want to track.
filter_to_domainstringCheck for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domainstringCheck for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_bodyintegerSet to 1 to include message bodies in the result.
body_typestringUsed when include_body is set to get only body parts of a given MIME-type (for example text/html)
include_headermixedSet to 1 or raw to include message headers in the result.

Response body

{
  "success": booleanWhether the operation worked,
  "webhook_id": stringId of the webhook that has been created,
  "resource_url": stringComplete URL of the new webhook
}

WebHooks instance

GET: Properties of a given WebHook

GET https://api.context.io/2.0/accounts/id/webhooks/webhook_idtest it
idUnique id of an account accessible through your API key
webhook_idUnique id of the webhook instance.

Response body

{
  "callback_url": stringYour callback URL to which we'll POST message data,
  "failure_notif_url": stringYour callback URL for failure notifications,
  "active": booleanWhether this webhook is currently applied to new messages we find in the account or not,
  "failure": booleantrue means we're having issues connecting to the account and gave up after a couple retries. The failure_notif_url is called when a webhook's failure property becomes true.,
  "webhook_id": stringId of the webhook,
  filter_*: stringValue of a filter assigned to this webhook when created,
  ...
}

POST: Change properties of a given WebHook

POST https://api.context.io/2.0/accounts/id/webhooks/webhook_idtest it
idUnique id of an account accessible through your API key
webhook_idUnique id of the webhook instance.

Parameters

nametypedescription
optional:
callback_urlstring
(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.
failure_notif_urlstring
(url)
A valid URL Context.IO calls if the WebHooks fails and will no longer be active. That may happen if, for example, the server becomes unreachable or if it closes an IDLE connection and we can't re-establish it.

The callback URL is called with an HTTP POST with more information in request body, see receiving failure notifications.
activeintegerThe active property of a WebHook allows you to pause (set to 0) or resume (set to 1) it.
filter_tostringCheck for new messages sent to a given name or email address. Also accepts a comma delimited list of email addresses.
filter_fromstringCheck for new messages received from a given name or email address. Also accepts a comma delimited list of email addresses.
filter_ccstringCheck for new messages where a given name or email address is cc'ed. Also accepts a comma delimited list of email addresses.
filter_subjectstringCheck for new messages with a subject matching a given string or regular expresion
filter_threadstringCheck for new messages in a given thread. Value can be a gmail_thread_id or the email_message_id or message_id of an existing message currently in the thread.
filter_new_importantstringCheck for new messages automatically tagged as important by the Gmail Priority Inbox algorithm.

To trace all messages marked as important (including those manually set by the user), use filter_folder_added with value \Important. Note the leading back-slash character in the value, it is required to keep this specific to Gmail Priority Inbox. Otherwise any message placed in a folder called "Important" would trigger the WebHook.
filter_file_namestringCheck 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_addedstringCheck for messages filed in a given folder. On Gmail, this is equivalent to having a label applied to a message. The value should be the complete name (including parents if applicable) of the folder you want to track.
filter_folder_removedstringCheck for messages removed from a given folder. On Gmail, this is equivalent to having a label removed from a message. The value should be the complete name (including parents if applicable) of the folder you want to track.
filter_to_domainstringCheck for new messages sent to a given domain. Also accepts a comma delimited list of domains.
filter_from_domainstringCheck for new messages sent from a given domain. Also accepts a comma delimited list of domains.
include_bodyintegerSet to 1 to include message bodies in the result.
body_typestringUsed when include_body is set to get only body parts of a given MIME-type (for example text/html)
include_headermixedSet to 1 or raw to include message headers in the result.

Response body

{
  "success": booleanWhether modification succeeded,
  "feedbackCode": stringInformation about the request

}
Temporarily pausing a WebHook

If you need to temporarily pause WebHook for any reason, simply POST with active parameter set to 1 to pause that specific webhook.

DELETE: Cancel a WebHook

DELETE https://api.context.io/2.0/accounts/id/webhooks/webhook_idtest it
idUnique id of an account accessible through your API key
webhook_idUnique id of the webhook instance.

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. This lets our servers to complete the sync process, thus allowing you to fetch additional information related to the webhook.

Request body

The body of this request is a JSON object which includes information about the webhook, a token and signature to validate its origin and information about the message that matched your webhook:

{
    "account_id": stringAccount who owns the webhook,
    "webhook_id": stringId of the webhook that has been triggered,
    "timestamp": numberServer time for the request as a Unix timestamp,
    "message_data": {
      "email_message_id": stringValue of RFC-822 Message-ID header,
      "addresses": objectEmail addresses and names of sender and recipients (more details),
      "person_info": objectAdditional info about contacts on this message (more details),
      "message_id": stringUnique and persistent id assigned by Context.IO to the message,
      "gmail_message_id": stringMessage id assigned by Gmail (only present if source is a Gmail account),
      "gmail_thread_id": stringThread id assigned by Gmail (only present if source is a Gmail account),
      "references": arrayList of email_message_ids that are in the same message thread,
      "files": [
        {
          "size": numberSize of the attachment in bytes,
          "type": stringValue of Content-type header for the attachment,
          "file_name": stringFull name of the file attached,
          "file_name_structure": arrayName of the file broken down in semantic parts (more details),
          "body_section": stringIdentifies MIME body part the attachment can be found in,
          "file_id": stringUnique and persistent id assigned by Context.IO to the file,
          "is_embedded": booleanIndicates whether this file is an object embedded in the message or not,
          "content_disposition": stringValue of the Content-Disposition header of the MIME part containing this file, if specified. Typically 'inline' or 'attachment',
          "content_id": stringIf this file is an embedded object, this is the value of the Content-Id header of the MIME part containing this file
        },
        ...
      ],
      "date": numberUnix timestamp of message date,
      "date_indexed": numberTime this message was first seen by Context.IO (Unix timestamp),
      "subject": stringSubject of the message,
      "folders": arrayList of folders (or Gmail labels) this message is found in,
      "sources": [
        {
          "label": stringLabel of the source containing this message,
          "resource_url": stringComplete URL of the source
        },
        ...
      ]
    },
    "token": stringRandom string used to calculate signature,
    "signature": stringHMAC-SHA256 hash of the timestamp and token with your Context.IO secret as the hashing key
}
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.

Here's an example in PHP of how you would authenticate a request to your callback url:

<?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 authentified
}
else {  
  // invalid request, you can ignore it 
}
?>
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.

Accepting POST requests with application/json Content-type in mod_security

Change:

SecFilterSelective HTTP_Content-Type \
"!(^$|^application/x-www-form-urlencoded$|^multipart/form-data;)"

to:

SecFilterSelective HTTP_Content-Type \
"!(^$|^application/x-www-form-urlencoded$|^multipart/form-data;|^application/json$)"

[reference]

Accepting POST requests with application/json Content-type in mod_security 2

Change:

SecRule HTTP_Content-Type \
"!(^application/x-www-form-urlencoded|^multipart/form-data;).*$"

to:

SecRule HTTP_Content-Type \
"!(^application/x-www-form-urlencoded|^multipart/form-data;|^application/json).*$"

[reference]