A brief overview of the heliotrope api

Heliotrope works with JSON over HTTP and is a RESTful service. Here is a listing of the available calls you can do to Heliotrope.

Note: Every call that ends with a .json in the resource path will ask for a JSON object. If you omit it, you will ask for the same resource in HTML if applicable.

At the server level

Information

Request

GET /info.json

Response

{
     "response": "ok",
     "status": "up",
     "api_version": "0.1"

}

Size

Request

GET /size.json

Response

{
    "response": "ok",
    "size": 3240
}

where size represents the number of messages on the server

Labels

More info on the labels

Request

GET /labels.json

Response

{
    "labels": [
        "attachment",
        "spam",
        "sup",
        "starred",
        "inbox",
        "family",
        "work"
    ],
    "response": "ok"
}

Labels pruning

Deletes labels that are not used anymore (ie no thread/label is still tagged with it)

Request

POST /labels/prune.json

parameters:

• anything (can be an empty object)

Response

Same as GET labels.json

Contacts

Get a list of the contacts automatically retrieved from the emails starting with a prefix, or all of them.

Request

GET /contacts.json

parameters:

• prefix: a string to search for. Every contact that has this prefix as the beginning of its name or email field will match. It doesn't work for strings in the middle of those fields.
• num: the max number of results. Defaults to 20.

Response

{
    "response": "ok",
    "contacts": [
        {
            "name": "Matthieu Rakotojaona",
            "email": "matthieu.rakotojaona@gmail.com"
        }
    ]
}

Search

Search for threads that match a certain query. Pagination is built-in; by default you query for all the result (hard-limited to 300 results). If you want more results, you have to use the parameters.

Request

GET /search.json

Parameters:

• q: the query. Must be a Heliotrope-valid (ie Whistlepig-valid) query.
• start: where to start from. If you want the results starting from the third one, use start=3
• num: how many results to output at most. Defaults to 20.

If you want to implement some kind of pagination with 12 results per page, you will query these resources:

• /search.json?q="some query"&start=0&num=12
• /search.json?q="some query"&start=12&num=12
• /search.json?q="some query"&start=24&num=12
• ...

until you have less than 12 results; You know that you are on the last page.

Response

{
    "response": "ok",
    "results": [
        {
            "subject": "[sup-talk] Cannot view old messages",
            "date": 1301816891,
            "participants": [
                "Ruthard Baudach <rthrd@web.de>",
                "Tero Tilus <tero@tilus.net>"
            ],
            "direct_recipients": [
                "sup-talk <sup-talk@rubyforge.org>",
                "Sup users <sup-talk@rubyforge.org>"
            ],
            "indirect_recipients": [],
            "size": 2,
            "thread_id": 2795,
            "state": [],
            "labels": [
                "sup"
            ],
            "snippet": "I've got a strange problem: I cannot view old messages in my mbox. This mbox is several years old, a",
            "unread_participants": []
        },
        {
            "subject": "[sup-talk] Fwd: Re: Cannot view old messages",
            "date": 1301927681,
            "participants": [
                "Ruthard Baudach <rthrd@web.de>"
            ],
            "direct_recipients": [
                "sup-talk <sup-talk@rubyforge.org>"
            ],
            "indirect_recipients": [],
            "size": 1,
            "thread_id": 2793,
            "state": [],
            "labels": [
                "sup"
            ],
            "snippet": "From: Ruthard Baudach <ruthard.baudach@web.de> To: sup-talk <sup-talk@rubyforge.org> Date: Mon, 04 A",
            "unread_participants": []
        }
    ]
}

Notes

• This resource is available as HTML by using the following query :

GET /search

• The root of the server automatically redirects to the inbox: calling

GET /

is equivalent to calling

GET /search?q=~inbox

Count

Count the number of threads that match the specified query

Request

GET /count.json

Parameters:

• q: The query. Behaves exactly like the search.json resource.

Response

{
     "response":"ok",
     "count":62
}

At the Thread level

Thread API

At the Message level

Message API