accounts/sources

Multiple sources on a single account

You can have more than one source for a single account. In this case, data from all these sources are merged and considered as one data set on which the other accounts sub-resources interact.

In other words, this is meant to handle users of your application with than one email account who always wants your application to show data from all of these accounts as if they were one.

If you want to be able to query IMAP sources separately, create two accounts (one for each IMAP source)

Using OAuth to connect to email account instead of password

Context.IO supports OAuth authentication for IMAP when adding a Gmail or Google Apps email accounts as a source.

To use it, you first need to configure the OAuth consumer key you obtained from Google as an OAuth provider. Then, when adding sources to accounts in Context.IO set the provider_consumer_key, provider_token and provider_token_secret instead of the password.

Implementing OAuth isn't always straightforward. Have a look at connect_tokens as an easy way to support it.

Supported methods

List methods:GETPOST

Instance methods:GETDELETEPOST

Sub-resources

folders sync

Sources list

GET: List of IMAP sources assigned for an account

Parameters

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

POST: Add a mailbox to a given account

Parameters

name	type	description
required:
email	string	The primary email address used to receive emails in this account
server	string	Name of IP of the IMAP server, eg. imap.gmail.com
username	string	The username used to authentify an IMAP connection. On some servers, this is the same thing as the primary email address.
use_ssl	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	integer	Port number to connect to on the server. Keep in mind that most IMAP servers will have one port for standard connection and another one for encrypted connection (see use-ssl parameter above)
type	string	Currently, the only supported type is IMAP
optional:
sync_period	string	Sets the period at which the Context.IO index for this source is synced with the origin email account on the IMAP server. Possible values are 1h, 4h, 12h and 24h (default).
raw_file_list	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	string	Password for authentication on the IMAP server. Ignored if any of the provider_* parameters are set below.
provider_token	string	An OAuth token obtained from the IMAP account provider to be used to authentify on this email account.
provider_token_secret	string	An OAuth token secret obtained from the IMAP account provider to be used to authentify on this email account..
provider_consumer_key	string	The OAuth consumer key used to obtain the the token and token secret above for that account. That consumer key and secret must be configured in your Context.IO account, see oauth_providers
callback_url	string (url)	If specified, we'll make a POST request to this URL when the initial sync is completed.

Callback notification for initial sync

If you specify a callback_url when you create a source, we'll make a POST request to that URL when the initial sync of the mailbox is completed.

Request body

The body of this request is a JSON object which includes information about the source whose initial sync just completed along with a token and signature to authentify its origin:

{
  "account_id": stringAccount who owns the source,
  "source_label": stringLabel of the source,
  "timestamp": numberServer time the initial import was completed,
  "token": stringRandom string used to calculate signature,
  "signature": stringHMAC-SHA256 hash of timestamp and token with your Context.IO secret as the hashing key
}

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

For a code example, see the documentation about webhook callbacks.

Source Instance

source label

Context.IO assigns a label to every source. This label is used to refer to individual sources.

GET: Parameters and status for an IMAP source.

POST: Modify a data source on a given account

Parameters

name	type	description
optional:
status	integer	If the status of the source is TEMP_DISABLED or DISABLED. You can do a POST/PUT with status set to 1 to reset it.
sync_period	string	Changes the period at which the Context.IO index for this source is synced with the origin email account on the IMAP server. Possible values are 1h, 4h, 12h and 24h (default).
password	string	New password for this source. Ignored if any of the provider_* parameters are set below.
provider_token	string	An OAuth token obtained from the IMAP account provider to be used to authentify on this email account.
provider_token_secret	string	An OAuth token secret obtained from the IMAP account provider to be used to authentify on this email account..
provider_consumer_key	string	The OAuth consumer key used to obtain the the token and token secret above for that account. That consumer key and secret must be configured in your Context.IO account, see oauth_providers

DELETE: Delete a data source of an account