1. Prerequisites

ElasticInbox requires:

  1. The most recent update of Java 7 (minimum is Java 6)
  2. Cassandra single or multi-node deployment running version 1.2.x (minimum supported version currently is 1.1.x; version 2.x is not fully tested yet). In this setup Cassandra cluster name is “Test Cluster”.

2. Installation

Download and unpack latest release:

cd /opt

wget https://github.com/elasticinbox/elasticinbox/releases/download/0.4.0/elasticinbox-0.4.0-bin.tar.gz

tar zxf elasticinbox-0.4.0-bin.tar.gz

cd elasticinbox-0.4.0

Initialize ElasticInbox keyspace:

$ cassandra-cli --host localhost
Connected to: "TestCluster" on localhost/9160
Welcome to Cassandra CLI version 1.2.3


[default@unknown] create keyspace ElasticInbox
... with placement_strategy = 'org.apache.cassandra.locator.SimpleStrategy'
... and strategy_options = {replication_factor:1};

Initialize ElasticInbox column families (Note: remove all comments from config/elasticinbox.cml before running following command):

cassandra-cli --host localhost -f config/elasticinbox.cml

3. Configuration

To setup ElasticInbox with local filesystem as blob storage update following fields in the config/elasticinbox.yaml:

cassandra_cluster_name: 'Test Cluster'

: filesystem
: /opt/elasticinbox-0.4.0
: blobs

Create local folders for blobs (as per config/elasticinbox.yaml above), logs (see config/logback.xml) and temporary files (see bin/elasticinbox):

mkdir /opt/elasticinbox-0.4.0/blobs
mkdir -p /var/log/elasticinbox
mkdir -p /var/tmp/elasticinbox

4. Starting up

Start application as background process:

nohup bin/elasticinbox &

If successful, you should see logs:

tail -100 /var/log/elasticinbox/elasticinbox.log

5. Interacting with REST

This is very simple example showing how you can store and retrieve messages using REST API.

Note: By default RESTful APIs are accessible on port 8181. You can change this from config/jetty.xml


1. Initialize new account:

curl -XPOST "http://localhost:8181/rest/v2/mydomain.tld/user"


HTTP/1.1 201 Created
Location: http://localhost:8181/rest/v2/mydomain.tld/user/mailbox


2. Store message in the Inbox (Label=1)

curl -XPOST "http://localhost:8181/rest/v2/mydomain.tld/user/mailbox/message?label=1" \
     -T testmail.eml


HTTP/1.1 201 Created
Location: http://localhost:8181/rest/v2/mydomain.tld/user/mailbox/message/e5031a10-f81d-11df-a88e-080027267700



3. Get pre-parsed message (served from Cassandra):

curl -XGET \


HTTP/1.1 200 OK
Content-Type: application/json

    "message": {
        "labels": [0, 1],
        "size": 1123,
        "date": "2010-11-24T22:55:12.000+0000",
        "subject": "Hello World!",
        "location": "blob://fs-local/e5031a10-f81d-11df-a88e-080027267700?c=dfl",
        "from": [{
                "address": "test@elasticinbox.com",
                "name": "John Doe" }],
        "to": [{
                "address": "user@mydomain.tld",
                "name": "My Name" }],
        "htmlBody": "This is sample <u>html</u> message body.<br><br>-- EI<br>"


4. Get raw message (served from blob store):

curl -XGET \


HTTP/1.1 200 OK
Content-Type: text/plain
Transfer-Encoding: chunked

Received: from mx02 (mx02 [])
        by mx02 (Postfix, from userid 48)
    id AB80628CA95; Mon, 05 Dec 2011 09:53:50 -0800 (PST)
Date: Mon, 5 Dec 2011 21:53:48 +0400
To: =?utf-8?B?w4dhdGTEsXLEsWxtYWzEsSDDnG52YW4=?= <user@mydomain.tld>
From: =?utf-8?B?UsO8c3TJmW0gxo9saXlldg==?= <test@elasticinbox.com>
Subject: =?utf-8?B?VVRGOCBUZXN0IMO8w6fDvG4gbcO2dnp1IGZpa2lsyZnFn23JmW1pxZ/JmW0=?=
Message-ID: <3917ea5a412bc64e0c1f04d81ac2e5c6@elasticinbox.com>


For the complete REST API documentation visit api.elasticinbox.com.

6. Interacting with LMTP

Messages can be delivered using standard LMTP protocol.

Note: By default LMTP port is set to 2400 and can be changed from config/elasticinbox.yaml

You can use smtp-source application which usually ships with Postfix to test LMTP:

smtp-source -L -s 1 -l 1 -m 1 -c -f from@example.com -t to@example.com -F test-email.eml localhost:2400