users

Supported methods

List methods:GETPOST

Instance methods:GETDELETEPOST

Sub-resources

connect_tokens email_accounts webhooks

users list

GET: List of users

GET https://api.context.io/lite/userstest it

Parameters

nametypedescription
optional:
emailstringOnly return users associated with this email address
statusstringOnly return users with email accounts with the specified status. If a user has many email accounts, only those matching the given value will be included in the response. Possible statuses are: INVALID_CREDENTIALS, CONNECTION_IMPOSSIBLE, OK, TEMP_DISABLED and DISABLED.
status_okintegerSet to 0 to get all users with email accounts that are not working correctly. Set to 1 for the opposite. As for the status filter above, only email accounts matching the specific value are included in the response.
limitintegerThe maximum number of results to return. The maximum limit is 100.
offsetintegerStart the list at this offset (zero-based).

Response body

[
  {
    "id": stringID of the user,
    "username": stringUsername assigned to the user,
    "created": numberUnix timestamp of user creation time,
    "suspended": numberUnix timestamp of user suspension time 0 means not suspended,
    "email_addresses": arrayArray of email addresses for this user,
    "first_name": stringFirst name of user,
    "last_name": stringLast name of user,
    "password_expired": numberUnix timestamp of user's password expiration. 0 means still valid,
    "email_accounts": arrayList of email accounts where this user gets data from. See email_accounts for details
    "resource_url": stringThe URL of the user list resource,
  },
  ...
]

POST: Add a new user

POST https://api.context.io/lite/userstest it

Parameters

nametypedescription
optional:
migrate_account_idstringExisting account_id you want to migrate to lite. Either migrate_account_id or email must be specified
emailstringThe primary email address of the user. Either email or migrate_account_id must be specified
first_namestringFirst name of the user
last_namestringLast name of the user
serverstringThe DNS name or IP of the email server, eg. imap.gmail.com. See creating a user and an email account in a single call for details
usernamestringThe username used to authenticate the email account. On some servers, this is the same as the primary email address. See creating a user and an email account in a single call for details
use_sslintegerSet to 1 if you want SSL encryption to be used when opening connections to the server. Any other value will be considered as "do not use SSL". See creating a user and an email account in a single call for details.
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). See creating a user and an email account in a single call for details
typestringThe email protocol to use for the account. The only supported value currently is IMAP. See creating a user and an email account in a single call for details
passwordstringPassword for authentication on the email server. Ignored if any of the provider_* parameters are set below. See creating a user and an email account in a single call for details
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.

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.

Response body

{
  "success": booleantrue if user has been created (HTTP status 201), false on error,
  "id": stringId of the user that has been created,
  "resource_url": stringFull URI of resource created
  If your key uses 3-legged signatures, the following 2 properties are added
  "access_token": stringOAuth access token to sign all future requests on this newly created user,
  "access_token_secret": stringOAuth access token secret to sign all future requests on this newly created user
}
NOTE: If the post was unsuccessful, a totally different return schema is used

Creating a user and an email account in a single call

The POST call to create a user also accepts all parameters used to create a email account.

Beyond the convenience of doing both operation in a single call, this has the advantage of making error handling easier. If the email account parameters aren't valid or don't map to an existing and accessible mailbox, the user isn't created and this call fails.

Response body when creating a email account in the same call
{
  "success": booleantrue if user has been created (HTTP status 201), false on error,
  "id": stringId of the user that has been created,
  "resource_url": stringFull URI of resource created,
  "email_account": {
    "label":stringLabel of the email account that has been created,
    "resource_url":stringFull URI of the email account created for the user
  }
  If your key uses 3-legged signatures, the following 2 properties are added
  "access_token": stringOAuth access token to sign all future requests on this newly created user,
  "access_token_secret": stringOAuth access token secret to sign all future requests on this newly created user
}

user instance

GET: Details about a given user

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

Response body

{
  "id": stringID of the user,
  "username": stringUsername assigned to the user,
  "created": numberUnix timestamp of user creation time,
  "suspended": numberUnix timestamp of user suspension time 0 means not suspended,
  "email_addresses": arrayArray of email addresses for this user,
  "first_name": stringFirst name of user,
  "last_name": stringLast name of user,
  "password_expired": numberUnix timestamp of user's password expiration. 0 means still valid,
  "email_accounts": arrayList of email accounts where this user gets data from. See email_accounts for details,
  "resource_url": stringThe URL of the user resource,
}

DELETE: Remove a given user

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

POST: Modify a given user

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

Parameters

nametypedescription
optional:
first_namestringFirst name of the user
last_namestringLast name of the user

Response body

{
  "success": booleantrue if user has been updated, false on error,
  "resource_url": stringThe URL of the updated user resource,
}