API version:
  • 1.0
  • 1.1
  • 2.0

accounts/messages/folders

Note that for Gmail and Google Apps, this resource maps to the "labels" assigned to the message.

Supported methods

GETPOSTPUT

GET: List of folder a message is in
GET https://api.context.io/2.0/accounts/id/messages/message_id/folderstest 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.

Response body

[
  {
    "name": stringName of an IMAP folder, 
    "symbolic_name": stringSpecial-use attribute of this folder (if and only if the server supports it and applicable to this folder)
  }, 
  ...
]

POST: Edit folders a message should appear in

While you can copy/move a message in a given folder with the POST method on a given message, this allows a more flexible way to add or remove folder(s) a message should appear in.

POST https://api.context.io/2.0/accounts/id/messages/message_id/folderstest 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
optional:
addstringNew folder this message should appear in.
removestringFolder this message should be removed from.

Response body

{
  "success": booleanwhether or not the specified folders were added/removed
}
Adding/removing more than one folder

This call supports adding and/or removing more than one folder simultaneously using the [] suffix to the parameter name.

For example, the call below will remove the message from the INBOX folder and add it to folders named new folder 1 and new folder 2.

POST /2.0/accounts/4c1478ab8ead000b051f0006/messages/4f5e35243f757e123e000063/folders HTTP/1.1
Host: api.context.io
Accept: */*
Authorization: OAuth oauth_version="1.0",oauth_nonce="077a8b9c028fe45acf14228429908ea4",oauth_timestamp="1332791306",oauth_consumer_key="kfuy5mb0",oauth_signature_method="HMAC-SHA1",oauth_signature="25dAo6xjLaJQySng6v4FoGhASlM%3D"
Content-Length: 66
Content-Type: application/x-www-form-urlencoded

add[]=new%20folder%201&add[]=new%20folder%202&remove=INBOX

PUT: Set folders a message should appear in

The PUT command allows you to completely overwrite which folder(s) a message should appear by specifying the set in the request body.

PUT https://api.context.io/2.0/accounts/id/messages/message_id/folderstest 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.

The format of the request body follows the format of the GET response above with the exception that you only need to specify either the name or symbolic_name property for each folder the message must appear in.

As shown in the example below, if you want to set folders using the symbolic names as returned by the XLIST command, make sure you escape the \ character.

Example request

PUT /2.0/accounts/4c1478ab8ead000b051f0006/messages/4f5e35243f757e123e000063/folders HTTP/1.1
Host: api.context.io
Accept: */*
Authorization: OAuth oauth_version="1.0",oauth_nonce="077a8b9c028fe45acf14228429908ea4",oauth_timestamp="1332791306",oauth_consumer_key="kfuy5mb0",oauth_signature_method="HMAC-SHA1",oauth_signature="25dAo6xjLaJQySng6v4FoGhASlM%3D"
Content-Length: 59
Content-Type: application/json

[{"name":"my personal label"},{"symbolic_name":"\\Starred"},{"name":"parent folder/child folder"}]