API
BitMaelum communicates client/server and server/server through the same HTTP/JSON api. A server has both authenticated and unauthenticated endpoints.
GET /
PUBLIC: information about the server. Mostly displaying a logo for now
POST /account/<hash>
creates a new account on the server
GET /account/<hash>
PUBLIC: Finger account. Get information about the given account or organization. (@TODO: do we want this?)
GET /account/<hash>/keys
PUBLIC: retrieves the public keys for this account
POST /ticket
PUBLIC: retrieves a ticket for uploading messages. Can return a valid or invalid ticket. When invalid, it
needs to validate the ticket by doing proof-of-work and upload the ticket again
POST /incoming/header
PUBLIC: uploads a message header. There can be multiple message headers for each message. Headers can only be
uploaded with a valid ticket in the header
POST /incoming/catalog
PUBLIC: uploads a message catalog. There can only be a single catalog for each message. Catalog can only be
uploaded with a valid ticket in the header.
POST /incoming/block/<id>
PUBLIC: uploads a message block. Blocks can only be uploaded with a valid ticket in the header.
POST /incoming/attachment/<id>
PUBLIC: uploads a message attachment. Attachments can only be uploaded with a valid ticket in the header.
POST /incoming
PUBLIC: Mark the message as fully uploaded. It will process the message. Only valid with a ticket in the header.
DELETE /incoming
PUBLIC: remove the message without sending. Only valid with a ticket in the header.
To authenticate, please see below.
GET /account/<hash>/boxes
retrieves a list of all mailboxes available
GET /account/<hash>/box/<box>
retrieves a (paginated) list of mail uuids and flags for this box
GET /account/<hash>/box/<box>/new?since=<timestamp>
retrieves a (paginated) list of mail uuids and flags for this box, where the flag "unseen" has been set.
POST /account/<hash>/message/box/<box>/<uuid>/flag/<flag>
Set flag for this specific message
DELETE /account/<hash>/message/box/<box>/<uuid>/flag/<flag>
Unset flag for this specific message
GET /account/<hash>/message/box/<box>/<uuid>/header
retrieve the header of a specific message
GET /account/<hash>/message/box/<box>/<uuid>/catalog
retrieve the catalog of a specific message
GET /account/<hash>/message/box/<box>/<uuid>/block/<id>
retrieve the given block of a specific message
GET /account/<hash>/message/box/<box>/<uuid>/attachment/<id>
retrieve the given attachment of a specific message
The store will be a system where we can add user-data from local and store it encrypted on the server. This can be used to save things like configuration, box names etc
GET /account/<hash>/contacts
Retrieves all contacts
POST /account/<hash>/contacts
Creates a new contact
DELETE /account/<hash>/contact/<contact>
Remove contact, also removed from contact groups if any
PUT /account/<hash>/contact/<contact>
Update contact
GET /account/<hash>/contactgroups
Retrieve all contact groups
POST /account/<hash>/contactgroup
Creates new contact group
PUT /account/<hash>/contactgroup/<group>/<contact>
Adds a contact to a contact group
DELETE /account/<hash>/contactgorup/<group>/<contact>
Remove a contact from a contact group
Authentication works via JWT tokens added to the Authorization header on each request.
Authorization: Bearer <jwttoken>
The JWT token is generated as follows:
{
"Sub": <address hash>
"Exp": <expiry time, max 1 hour>
}
And should be signed with RSA256 with your PRIVATE account key. This key must match the public key on the server for the given account.
These endpoints will probably be added in the near future:
mailinglists
/account/<id>/mailinglists
/account/<id>/mailinglist/<mailinglistid>/subscribe
/account/<id>/mailinglist/<mailinglistid>/unsubscribe
