Communications Protocol

This page describes how the IMAP and SMTP communication is wrapped in HTTP. It is quite straightforward.


All HTTP requests related to IMAP have a URL that starts "imap/".

IMAP connections are persistent, while HTTP connections are transient. To bridge this gap the http2email proxy keeps IMAP connections open for multiple HTTP connections.

A new IMAP connection is opened by requesting the empty URL "imap/". The proxy associates a unique ID (currently a 64-bit number, represented in hex) with each open IMAP connection. The ID for the new connection is returned in response to this request.

Subsequent requests refer to the connection by appending its ID to the "imap/" URL. The last part of the URL indicates the caracter set that the server should declare in its response.

To send an IMAP command, an HTTP request is made containing the IMAP command in the body. The proxy sends this to the IMAP connection (or queues it for sending) and returns immedately with an empty response.

To obtain the result of an IMAP command, and HTTP request is made to the URL containing the IMAP connection's unique ID with an empty body. If data can be read from the IMAP connection it is returned immediately in the body of the response. If no data can be read, the proxy waits until the IMAP connection becomes readable. There is a timeout (currently 60s) to prevent the browser or anything else from interrupting the waiting request.

It is essential that the browser always has a request waiting for IMAP data. This is for two reasons: first, the IMAP protocol allows the server to send the client data at any time, e.g. to notify it that new messages have arrived, and secondly, the proxy will time out and close the IMAP connection if it is unused for some time (currently 100s).


SMTP does not have many of the complexities of IMAP, and the protocol is simpler.

The browser prepares a complete "batched" SMTP session, i.e. a series of commands, and sends it in a single request to the "smtp/" URL. The proxy sends this data to the SMTP server one command at a time and checks the response code. It continues as long as it gets positive responses. If it receives an error response it will disconnect immediately. The response sent back to the browser is the series of responses received from the SMTP server.