Groxy

A JSON API proxy for talking to Gmail. Allows using persistent IMAP connections for non-resident scripting languages.

Usage

Clone the repo and start the application.

lein run

You can then browse the web application at:

http://localhost:4545

Endpoints

All endpoints (except /api) require you send the following parameters:

email - Your Gmail email address
access_token - A valid OAuth access token

By default For the 'All Mail' folder Groxy uses '[Gmail]/All Mail' - which will be incorrect for Google Mail accounts (and possibly others) which use '[Google Mail]/All Mail'.

To specify another folder to use the folder parameter to give its name. But be aware that the message IDs returned are folder specific, so you'll need to use these consistently.

API Status

GET /api

Searching

The endpoint searches the 'All Mail' folder.

GET /api/messages

With parameters:

query - Your query string (supports X-GM-RAW extension)
folder - The name of the folder to use

Single Messages

GET /api/messages/:messageid

With parameters:

messageid - The ID of the message to fetch
folder - The name of the folder to use

Attachments

GET /api/messages/:messageid/attachments/:attachmentid

You will also need specify the following parameters. This will stream back the raw content for the attachment.

messageid - The ID of the attachments message
attachmentid - The ID of the attachment to fetch
folder - The name of the folder to use

Access Tokens

Obtaining and refreshing access tokens is not handled by Groxy, you need to do this yourself. If you make a request with an invalid access token you'll receive a 403 response, which is your notification to refresh your token and try again.

To try Groxy out the easiest way is to get an access token from the OAuth Playground. But don't select the Gmail service listed, enter the scope explicitly as...

https://mail.google.com/

Configuration

Configuration is supplied via environment variables with the GROXY prefix.

GROXY_PORT=4545
GROXY_LOGFILE="logs/access.log"
GROXY_LOGLEVEL="debug"
GROXY_LOGPATTERN="%d %m"

Caching

By default Groxy will cache messages in memory using an LRU cache. To enable a database cache (via JDBC) you can configure it as follows...

GROXY_DB_CACHE_TYPE="mysql"
GROXY_DB_CACHE_DSN="//127.0.0.1:3306/db_name"
GROXY_DB_CACHE_USER="root"
GROXY_DB_CACHE_PASS=""

This will provide a durable cache that survives restarts.

Logging

Logging is configured to use log4j, and writes to the log file configured by GROXY_LOGFILE.

Java Classes

The library uses some Java classes to implement the custom Gmail X-GM-RAW IMAP extension. There are stored in src/java. You can compile these on their own using Leiningen.

lein javac

They will be built automatically once though when running the project (or via REPL).

Documentation

Documentation can be generated with Marginalia via Leiningen:

lein marg

And is then available in the docs folder.

Deployment

You can build a standalone WAR file for deployment using:

lein ring uberwar

This will build a version numbered file in target/groxy-X.X.X.war. Alternatively you can build an executable:

lein bin

The task will output the name of the executable built, but it should be target/groxy

boxuk / groxy