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 more than one email account who always want 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 OAuth2 to connect to email account instead of password

Context.IO supports OAuth2 authentication for IMAP when adding a Gmail/Google Apps or Microsoft Outlook.com accounts as a source.

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

Implementing OAuth2 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 connect_tokens

Sources list

GET: List of IMAP sources assigned for an account

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

Parameters

nametypedescription
optional:
statusstringOnly 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_okintegerSet 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

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

Parameters

nametypedescription
required:
emailstringThe primary email address used to receive emails in this account
serverstringName of IP of the IMAP server, eg. imap.gmail.com
usernamestringThe username used to authenticate an IMAP connection. On some servers, this is the same thing as the primary email address.
use_sslintegerSet 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"
portintegerPort 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)
typestringCurrently, the only supported type is IMAP
optional:
origin_ipstringIP address of the end user requesting the account to be created
expunge_on_deleted_flagintegerBy default, we don't filter out messages flagged as deleted. Set this parameter to 1 to turn on this filtering.
sync_all_foldersintegerBy default, we filter out some folders like 'Deleted Items' and 'Spam'. Set this parameter to 1 to turn off this filtering and show every single folder.
raw_file_listintegerBy 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.
passwordstringPassword for authentication on the IMAP server. Ignored if any of the provider_* parameters are set below.
provider_refresh_tokenstringAn OAuth2 refresh token obtained from the IMAP account provider to authenticate this email account.
provider_consumer_keystringThe 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_urlstring
(url)
If specified, we'll make a POST request to this URL when the initial sync is completed.
status_callback_urlstring
(url)
If specified, we'll make a POST request to this URL if the connection status of the source changes.

If you are handling OAuth authorization yourself and pass the refresh token to Context.IO there are some third party requirements (e.g. Google, Microsoft) to take note of, see OAuth provider scope.

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 authenticate 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
}
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.

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.

GET https://api.context.io/2.0/accounts/id/sources/labeltest it
idUnique id of an account accessible through your API key
labelThe label property of the source instance. You can use 0 as an alias for the first source of an account.

POST: Modify a data source on a given account

POST https://api.context.io/2.0/accounts/id/sources/labeltest it
idUnique id of an account accessible through your API key
labelThe label property of the source instance. You can use 0 as an alias for the first source of an account.

Parameters

nametypedescription
optional:
statusintegerIf the status of the source is TEMP_DISABLED or DISABLED. You can do a POST/PUT with status set to 1 to reset it.
force_status_checkintegerSet to 1 to create an IMAP connection and reset the source status to to one reported by the IMAP backend. Don't combine this with other parameters.
sync_all_foldersintegerBy default, we filter out some folders like 'Deleted Items' and 'Spam'. Set this parameter to 1 to turn off this filtering and show every single folder.
expunge_on_deleted_flagintegerBy default, we don't filter out messages flagged as deleted. Set this parameter to 1 to turn on this filtering.
passwordstringNew password for this source. Ignored if any of the provider_* parameters are set below.
provider_refresh_tokenstringAn OAuth2 refresh token obtained from the IMAP account provider to authenticate this email account.
provider_consumer_keystringThe 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
status_callback_urlstring
(url)
If specified, we'll make a POST request to this URL if the connection status of the source changes.

DELETE: Delete a data source of an account

DELETE https://api.context.io/2.0/accounts/id/sources/labeltest it
idUnique id of an account accessible through your API key
labelThe label property of the source instance. You can use 0 as an alias for the first source of an account.