API version:
  • 1.0
  • 1.1
  • 2.0

accounts/sources/folders/messages

This call returns the same message data as the messages resource but instead of returning whatever is available from the metadata index we maintain, it checks the IMAP server for new messages and includes thoses in the response.

The advantage is a list of message that reflects what's on the IMAP server at the moment the call is made vs. what was there the last time we synched with it. The downside is longer response time, a restricted set of parameters to filter results, and the fact the listing only works on a per-folder basis instead of all messages in the account.

This call will synchronously check the IMAP server for new emails and fetch them to update the index before sending the response. Don't expect to get a response in less than 1 second.

Supported methods

List methods:GET

Messages list

GET: Listings of email messages in a given folder
GET https://api.context.io/2.0/accounts/id/sources/label/folders/folder/messagestest 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.
folderThe full folder path using / as the path hierarchy delimiter.

Parameters

nametypedescription
optional:
include_bodyintegerSet to 1 to include message bodies in the result. Since message bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter.
body_typestringUsed when include_body is set to get only body parts of a given MIME-type (for example text/html)
include_headersmixedCan be set to 0 (default), 1 or raw. If set to 1, complete message headers, parsed into an array, are included in the results. If set to raw, the headers are also included but as a raw unparsed string. Since full original headers bodies must be retrieved from the IMAP server, expect a performance hit when setting this parameter.
include_flagsintegerSet to 1 to include IMAP flags for this message in the result. Since message flags must be retrieved from the IMAP server, expect a performance hit when setting this parameter.
flag_seenintegerSet to 1 to restrict list to messages having the \Seen flag set, set to 0 to have the messages with that flag unset (ie. list unread messages in the folder).
limitintegerThe maximum number of results to return.
offsetintegerStart the list at this offset (zero-based).

Response body

The response format is the same as the messages resource.

[
  {
    "date": numberUnix timestamp of message date,
    "date_indexed": numberTime this message was first seen by Context.IO (unix timestamp),
    "addresses": objectEmail addresses and names of sender and recipients (more details),
    "person_info": objectAdditional info about contacts on this message (more details),
    "email_message_id": stringValue of RFC-822 Message-ID header,
    "message_id": stringUnique and persistent id assigned by Context.IO to the message,
    "gmail_message_id": stringMessage id assigned by Gmail (only present if source is a Gmail account),
    "gmail_thread_id": stringThread id assigned by Gmail (only present if source is a Gmail account),
    "files": [
      {
        "size": numberSize of the attachment in bytes,
        "type": stringValue of Content-type header for the attachment,
        "file_name": stringFull name of the file attached,
        "file_name_structure": arrayName of the file broken down in semantic parts (more details),
        "body_section": numberIdentifies MIME body part the attachment can be found in,
        "file_id": stringUnique and persistent id assigned by Context.IO to the file,
        "is_embedded": booleanIndicates whether this file is an object embedded in the message or not,
        "content_disposition": stringValue of the Content-Disposition header of the MIME part containing this file, if specified. Typically 'inline' or 'attachment',
        "content_id": stringIf this file is an embedded object, this is the value of the Content-Id header of the MIME part containing this file
      },
      ...
    ],
    "subject": stringSubject of the message,
    "folders": arrayList of folders (or Gmail labels) this message is found in,
    "sources": [
      {
        "label": stringLabel of the source containing this message,
        "resource_url": stringComplete URL of the source
      },
      ...
    ]
  },
  ...
]