connect_tokens
While your code can create a new account and connect an email account to it with API calls, you still need to implement to UI for this in your app, including the process to obtain OAuth tokens from Gmail and Google Apps users.
To make this easier, Context.IO provides the connect_tokens resource. When users are ready to connect their email account to it, your app simply obtains a new connect_token and redirect users to the corresponding URL included in the POST response.
Users will then be presented with a standard form to either complete their IMAP settings or grant your application access through OAuth. Once the process is complete, control is passed back to your app. The sequence is illustrated below.
Supported methods
connect_tokens list
GET: List of connect tokens created with your API key
Response body
[
{
"token": stringId of the connect_token,
"email": stringemail address specified on token creation,
"created": numberUnix timestamp of the connect_token was created,
"used": numberUnix time this token was been used. 0 means it no account has been created with this token yet,
"expires": mixedUnix time this token will expire and be purged. Once the token is used, this property will be set to false,
"callback_url": stringURL of your app we'll redirect the browser to when the account is created,
"first_name": stringFirst name specified on token creation,
"last_name": stringLast name specified on token creation,
"account": {
If the connect_token hasn't been used yet, this object will be empty
"id": stringId of the account created with this token,
"created": numberUnix timestamp of account creation time,
"suspended": numberUnix timestamp of account suspension time 0 means not suspended,
"email_addresses":arrayArray of email addresses for this account. This only lists the actual addresses as strings.,
"first_name": stringFirst name of account holder,
"last_name": stringLast name of account holder,
"sources": arrayList of sources this account gets data from. See sources
}
},
...
]
POST: Obtain a new connect_token
Parameters
| name | type | description |
|---|---|---|
| required: | ||
| callback_url | 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: | ||
| 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 | string | First name of the account holder. |
| last_name | string | Last name of the account holder. |
| source_callback_url | string | If specified, we'll make a POST request to this URL when the initial sync is completed. |
| source_sync_all_folders | integer | By default, we filter out some filders like 'Deleted Items' and 'Drafts'. Set this parameter to 1 to turn off this filtering and show every single folder. |
| source_sync_flags | integer | By default, we don't synchronize IMAP flags. Set this parameter to 1 to turn on IMAP flag syncing for the 'seen' and 'flagged' flags. |
| source_raw_file_list | integer | By default, we filter out files like signature images from the files list. Set this parameter to 1 to turn off this filtering and show every single file attachment. |
Response body
{
"success": string true if connect_token was successfully created, false otherwise,
"token": stringId of the token,
"resource_url": stringURL to of the token,
"browser_redirect_url": stringRedirect the user's browser to this URL to have them connect their mailbox through this token
}
Unused connect_tokens are purged after 24 hours, see more details below.
The browser_redirect_url property returned when you create a new connect_token is intended to be used by your end user to connect their email account to your application. Therefore, it 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 of a connect_token).
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.
connect_token instance
GET: Information about a given connect token
Response body
{
"token": stringId of the connect_token,
"email": stringemail address specified on token creation,
"created": numberUnix timestamp of the connect_token was created,
"used": numberUnix time this token was been used. 0 means it no account has been created with this token yet,
"expires": mixedUnix time this token will expire and be purged. Once the token is used, this property will be set to false,
"callback_url": stringURL of your app we'll redirect the browser to when the account is created,
"first_name": stringFirst name specified on token creation,
"last_name": stringLast name specified on token creation,
"account": {
If the connect_token hasn't been used yet, this object will be empty
"id": stringId of the account created with this token,
"created": numberUnix timestamp of account creation time,
"suspended": numberUnix timestamp of account suspension time 0 means not suspended,
"email_addresses":arrayArray of email addresses for this account. This only lists the actual addresses as strings.,
"first_name": stringFirst name of account holder,
"last_name": stringLast name of account holder,
"sources": arrayList of sources this account gets data from. See sources
}
}
