accounts/messages

Supported methods

List methods:GETPOST

Instance methods:GETPOSTDELETE

Sub-resources

body flags folders headers source thread

Messages list

GET: Listings of email messages for an account

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

List filters

Each of the email, to, from, cc and bcc parameters can be set to a comma-separated list of email addresses. These multiple addresses are treated as an OR combination.

You can set more than one parameter when doing this call. Multiple parameters are treated as an AND combination.

nametypedescription
optional:
subjectstringGet messages whose subject matches this search string. To use regular expressions instead of simple string matching, make sure the string starts and ends with /.
emailstringEmail address or top level domain of the contact for whom you want the latest messages exchanged with. By "exchanged with contact X" we mean any email received from contact X, sent to contact X or sent by anyone to both contact X and the source owner.
tostringEmail address of a contact messages have been sent to.
fromstringEmail address of a contact messages have been received from.
ccstringEmail address of a contact CC'ed on the messages.
bccstringEmail address of a contact BCC'ed on the messages.
folderstringFilter messages by the folder (or Gmail label). This parameter can be the complete folder name with the appropriate hierarchy delimiter for the mail server being queried (eg. Inbox/My folder) or the "symbolic name" of the folder (eg. \Starred). The symbolic name refers to attributes used to refer to special use folders in a language-independent way. See RFC-6154.
sourcestringFilter messages by the account source label.
file_namestringSearch for files based on their name. You can filter names using typical shell wildcards such as *, ? and [] or regular expressions by enclosing the search expression in a leading / and trailing /. For example, *.pdf would give you all PDF files while /\.jpe?g$/ would return all files whose name ends with .jpg or .jpeg
file_size_minintegerSearch for files based on their size (in bytes).
file_size_maxintegerSearch for files based on their size (in bytes).
date_beforeinteger
(Unix timestamp)
Only include messages before a given timestamp. The value this filter is applied to is the Date: header of the message which refers to the time the message is sent from the origin.
date_afterinteger
(Unix timestamp)
Only include messages after a given timestamp. The value this filter is applied to is the Date: header of the message which refers to the time the message is sent from the origin.
indexed_beforeinteger
(Unix timestamp)
Only include messages indexed before a given timestamp. This is not the same as the date of the email, it is the time Context.IO indexed this message.
indexed_afterinteger
(Unix timestamp)
Only include messages indexed after a given timestamp. This is not the same as the date of the email, it is the time Context.IO indexed this message.
include_thread_sizeintegerSet to 1 to include thread size in the result.
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.
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 of messages in the result. Since message flags 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_sourceintegerSet to 1 to include message sources in the result. Since message sources must be retrieved from the IMAP server, expect a performance hit when setting this parameter.
sort_orderstringThe sort order of the returned results. Possible values are asc and desc
limitintegerThe maximum number of results to return. The maximum limit is 100.
offsetintegerStart the list at this offset (zero-based).

Response body

[
  {
    "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": stringIdentifies 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
      },
      ...
    ]
  },
  ...
]

POST: Add a message in a given folder

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

Parameters

nametypedescription
required:
dst_sourcestringLabel of the source you want the message copied to
dst_folderstringThe folder within dst_source the message should be copied to
messagefileRaw RFC-822 message data. If you use the "view message source" function of your email client, what you'll see there is what we expect to receive here. Hint: you can get this with the accounts/messages/source call.
optional:
flag_seenintegerMessage has been read. Set this parameter to 1 to set the flag, 0 to unset it.
flag_answeredintegerMessage has been answered. Set this parameter to 1 to set the flag, 0 to unset it.
flag_flaggedintegerMessage is "flagged" for urgent/special attention. Set this parameter to 1 to set the flag, 0 to unset it.
flag_deletedintegerMessage is "deleted" for later removal. An alternative way of deleting messages is to move it to the Trash folder. Set this parameter to 1 to set the flag, 0 to unset it.
flag_draftintegerMessage has not completed composition (marked as a draft). Set this parameter to 1 to set the flag, 0 to unset it.
This request needs to be POSTed like a form with a file upload

The source of the message is sent like file uploads are sent through HTML forms. In other words, this POST request should be sent with a Content-Type of multipart/form-data. Our client libraries manage this but if you're making direct HTTP requests to Context.IO, here's an example of what such a request should look like.

POST /2.0/accounts/4f01234567890abcdef09876/messages/ HTTP/1.1
Host: api.context.io
Accept: */*
Authorization: OAuth oauth_consumer_key="abcdef1234",oauth_version="1.0",oauth_timestamp="1327695986",oauth_nonce="6dPrHNDrx5hzfHkn",oauth_signature_method="HMAC-SHA1",oauth_signature="MFOyvf5Ykcsn7une48kGW0Aharw%3D"
Content-Type: multipart/form-data; boundary=------someRandomBoundary
Content-Length: 1917

--------someRandomBoundary
Content-Disposition: form-data; name="dst_folder"

testFolder
--------someRandomBoundary
Content-Disposition: form-data; name="message"; filename="message.eml"
Content-Type: message/rfc822

Delivered-To: jim@bob.com
Received: by 101.42.118.54 with SMTP id hp10cs194007icb;
        Thu, 13 Jan 2012 15:02:20 -0700 (PDT)
Return-Path: <blahblahblah@someisp.com>
Received: from [192.168.1.5] (71-211-196-225.hlrn.bob.com. [71.211.196.225])
        by mx.bob.com with ESMTPS id u41si888834ybu.20.2011.10.13.14.54.54
        (version=TLSv1/SSLv3 cipher=OTHER);
        Thu, 13 Jan 2012 15:02:20 -0700 (PDT)
Received: from mail-gx0-f174.someisp.com (mail-gx0-f174.someisp.com [109.45.123.134])
        by mx.someisp.com with ESMTPS id u41si888834ybu.20.2011.10.13.14.54.54
        (version=TLSv1/SSLv3 cipher=OTHER);
        Thu, 13 Jan 2012 14:54:53 -0700 (PDT)
Message-ID: <2E973E2A.3150305@bob.com>
Date: Thu, 13 Jan 2012 15:54:50 -0600
From: Dave Davidson <blahblahblah@someisp.com>
User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.21) Gecko/20110831 Thunderbird/3.1.13
MIME-Version: 1.0
To: Jim Bob <jim@bob.com>
Subject: Just sending out a test message
Content-Type: multipart/alternative;
 boundary="------------030009050309030308020807"

This is a multi-part message in MIME format.
--------------030009050309030308020807
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

Yo! This is a test multi-part message.


--------------030009050309030308020807
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 7bit

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
  </head>
  <body bgcolor="#ffff00" text="#ff0000">
    Yo! This is a test multi-part message.<br>
  </body>
</html>

--------------030009050309030308020807--

--------someRandomBoundary--
To avoid having to download the message source and POST it back ...

If you simply want to move a message from a folder to another or between 2 sources on the same account, you can use the POST method on the message itself to avoid having to tranfer the complete message source from Context.IO to your app and back.

Response body

{
  "success": booleanWhether or not the call succeeded
}

Message instance

GET: File, contact and other information about a given email message

GET https://api.context.io/2.0/accounts/id/messages/message_idtest it
idUnique id of an account accessible through your API key
message_idUnique id of a message. This can be the message_id or email_message_id property of the message. The gmail_message_id (prefixed with gm-) can also be used.

As specified in the RFC822, the < and > at the beginning and end of the Message-ID are part of the value and should be included if you're putting an email_message_id in the url.

Parameters

nametypedescription
optional:
include_thread_sizeintegerSet to 1 to include thread size in the result.
include_bodyintegerSet to 1 to include the message body in the result. Since the body must be retrieved from the IMAP server, expect a performance hit when setting this parameter.
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.
body_typestringUsed when include_body is set to get only body parts of a given MIME-type (for example text/html)
include_sourceintegerSet to 1 to include message sources in the result. Since message sources must be retrieved from the IMAP server, expect a performance hit when setting this parameter.

Response body

{
  "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": stringIdentifies 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
    },
    ...
  ]
}

POST: Copy or move a message

This call allows you to copy or move a message between folders. If there are more than one sources on the account, you can use this call to copy/move the message between these sources. In this case, the dst_label parameter must identify the source you want to message to be copied/moved to.

Have a look at the messages/folders resource to get a more flexible way to manage which folders a message should appear in.

POST https://api.context.io/2.0/accounts/id/messages/message_idtest it
idUnique id of an account accessible through your API key
message_idUnique id of a message. This can be the message_id or email_message_id property of the message. The gmail_message_id (prefixed with gm-) can also be used.

Parameters

nametypedescription
required:
dst_folderstringThe folder within dst_source the message should be copied to
optional:
dst_sourcestringLabel of the source you want the message copied to. This field is required if you're moving a message that already exists in one source of the account to another source of that account. If you only want to move the message to a different folder within the same source, dst_folder is sufficient.
moveintegerBy default, this calls copies the original message in the destination. Set this parameter to 1 to move instead of copy.
flag_seenintegerMessage has been read. Set this parameter to 1 to set the flag, 0 to unset it.
flag_answeredintegerMessage has been answered. Set this parameter to 1 to set the flag, 0 to unset it.
flag_flaggedintegerMessage is "flagged" for urgent/special attention. Set this parameter to 1 to set the flag, 0 to unset it.
flag_deletedintegerMessage is "deleted" for later removal. An alternative way of deleting messages is to move it to the Trash folder. Set this parameter to 1 to set the flag, 0 to unset it.
flag_draftintegerMessage has not completed composition (marked as a draft). Set this parameter to 1 to set the flag, 0 to unset it.

Response body

{
  "success": booleanWhether or not the call succeeded,
  "connection_log": stringIf the call failed, This will contain error messages from IMAP server
}

DELETE: Delete a message

DELETE https://api.context.io/2.0/accounts/id/messages/message_idtest it
idUnique id of an account accessible through your API key
message_idUnique id of a message. This can be the message_id or email_message_id property of the message. The gmail_message_id (prefixed with gm-) can also be used.
For standard IMAP accounts

The DELETE method will delete messages from the source email server. In IMAP-speak, it will set the \Deleted flag on the message and then call the EXPUNGE command.

Once this is done, the message is gone forever, there's no way to bring it back.

The EXPUNGE command removes all messages in that folder that have the \Deleted flag set. If you want to avoid that, you can simply mark the message as deleted.

For Gmail and Google Apps accounts

For Gmail and Google Apps mailboxes, setting the \Deleted flag and calling the EXPUNGE command is equivalent to removing a "label" and results in that message still showing up in the "All Mail" folder and other labels also assigned to the message. See this Gmail Support entry for details.

So, if you call the DELETE method on a message we assume it's because you wanted that message deleted. Therefore, what actually happens for Gmail or Google Apps messages is we move it to the "[Gmail]/Trash" folder.