users/email_accounts

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 email account.

To use it, you first need to configure the OAuth2 consumer key you obtained from Google and Microsoft as an OAuth2 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 connect_tokens

email accounts List

GET: List of email accounts assigned to a user

GET https://api.context.io/lite/users/id/email_accountstest it
idUnique id of a user accessible through your API key

Parameters

nametypedescription
optional:
statusstringOnly return email accounts whose status is of a specific value. Possible statuses are: INVALID_CREDENTIALS, CONNECTION_IMPOSSIBLE, OK, TEMP_DISABLED and DISABLED
status_okintegerSet to 0 to get email accounts that are not working correctly. Set to 1 to get those that are.

Response body

[
  {
    "status": stringThe connection status, one of OK, CONNECTION_IMPOSSIBLE, INVALID_CREDENTIALS, TEMP_DISABLED, DISABLED,
    "resource_url": stringThe URL of the email account resource,
    "type": stringThe type of account, currently only IMAP is supported,
    "authentication_type": stringThe type of credentials used to connect, one of password, oauth,
    "use_ssl": booleanSet to _1_ if you want SSL encryption to be used when opening connections to the email server,
    "server": stringThe DNS name or IP of the email server, eg. imap.gmail.com,
    "label": stringThe ID of the account.  Context.IO assigns a label to every email account.,
    "username": stringUsername assigned to the email account,
    "port": numberPort number to connect to on the server,
  },
  ...
]

POST: Add a mailbox to a given user

POST https://api.context.io/lite/users/id/email_accountstest it
idUnique id of a user accessible through your API key

Parameters

nametypedescription
required:
emailstringThe primary email address for this account
serverstringThe DNS name or IP of the email server, eg. imap.gmail.com
usernamestringThe username used to authenticate the email account. On some servers, this is the same as the primary email address.
use_sslintegerSet to 1 if you want SSL encryption to be used when opening connections to the email 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 email servers will have one port for standard connection and another one for encrypted connection (see use_ssl parameter above)
typestringThe email protocol to use for the account. The only supported value currently is IMAP
optional:
passwordstringPassword for authentication on the email 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
status_callback_urlstring
(url)
If specified, we'll make a POST request to this URL if the connection status of the email_account changes.

Response body

{
  "status": stringThe connection status, one of OK, CONNECTION_IMPOSSIBLE, INVALID_CREDENTIALS, TEMP_DISABLED, DISABLED,
  "label": stringThe ID of the account.  Context.IO assigns a label to every email account,
  "resource_url": stringThe URL of the email account resource,
}

email account Instance

GET: Parameters and status for an email account.

GET https://api.context.io/lite/users/id/email_accounts/labeltest it
idUnique id of a user accessible through your API key
labelThe label property of the email account instance. You can use 0 as an alias for the first email account of a user.

Response body

{
  "status": stringThe connection status, one of OK, CONNECTION_IMPOSSIBLE, INVALID_CREDENTIALS, TEMP_DISABLED, DISABLED,
  "resource_url": stringThe URL of the email account resource,
  "type": stringThe type of account, currently only IMAP is supported,
  "authentication_type": stringThe type of credentials used to connect, one of password, oauth,
  "use_ssl": booleanSet to _1_ if you want SSL encryption to be used when opening connections to the email server,
  "server": stringThe DNS name or IP of the email server, eg. imap.gmail.com,
  "label": stringThe ID of the account.  Context.IO assigns a label to every email account.,
  "username": stringUsername assigned to the email account,
  "port": numberPort number to connect to on the server,
}

POST: Modify an email account on a given user

POST https://api.context.io/lite/users/id/email_accounts/labeltest it
idUnique id of a user accessible through your API key
labelThe label property of the email account instance. You can use 0 as an alias for the first email account of a user.

Parameters

nametypedescription
optional:
statusintegerIf the status of the email account 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 a connection and reset the email account status to to one reported by the backend. Don't combine this with other parameters.
passwordstringNew password for this email account. 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 email_account changes.

Response body

{
  "success": booleantrue if the update was successful,
  "resource_url": stringThe URL of the email account resource,
  "feedback_code": stringA description of the failure,
}

DELETE: Delete an email account of a user

DELETE https://api.context.io/lite/users/id/email_accounts/labeltest it
idUnique id of a user accessible through your API key
labelThe label property of the email account instance. You can use 0 as an alias for the first email account of a user.