Note: Throughout this document, replace :id and :bin etc with your values
- The Mailbox
- Streaming / Tailing incoming mail
- Raw MIME email
- Viewing the body of an email
- Security & Implementation
Creating a new mailbox
You can either visit the mail site address at:
https://letterb.in or send off a request to:
Which will return a payload like:
:bin_public_id is for example
:bin is the private ID of the bin.
Requesting the following will give you a JSON representation of the mailbox:
Likewise, you can request an individual emails’ body HTML using the following address:
:idis returned in the JSON response above per email.
attached: trueunder the attachments array refers to whether the attachment was inlined or attached.
Streaming / Tailing
You are able to stream mailbox updates by going to this endpoint:
An example request with cURL would be:
"received":"2016-05-23T10:40:06Z","id":"233b9b73-c841-4ecf-8e1c-30cfab34ab6c","attachments":} "received":"2016-05-23T10:42:06Z","id":"443dd273-cd41-ascf-8e1c-30cfab34abcc","attachments":} "received":"2016-05-23T10:44:06Z","id":"443b1173-c841-4ecf-8e1c-30cfab34abzz","attachments":} ...
New JSON payloads will come in as they arrive…
This can be combined with jq to filter out results. For example:
curl --no-buffer -s https://letterb.in/m/:bin/stream | jq --unbuffered --raw-output '.subject'
…would pull out the subject on incoming email
Raw MIME email
Raw MIME URLs are made up of:
:raw_mime_hash is returned in the JSON response of the mailbox.
Attachment URLs are made up of:
You can download a single attachment with (remember, replace
:bin with your bin’s ID):
You can get
Viewing the body of an email
You can fetch the body part of an email at this address:
:id can be found by first querying your bin’s JSON representation:
id which is a UUIDv4 identifier.
You can also fetch the embellished version (which includes some additional styling) by adding
?embellished to the URL:
Security & Implementation
Mailboxes have a TTL of 1 day (86400 seconds).
The same TTL is set for each attachment and email. The TTL of the mailbox is reset to 1 day ever time a new email comes in.
Emails are in a per bin queue using Redis. That queue is truncated to a maximum of 10 emails.
Email ID’s are UUIDv4 and all date times are ISO8601.
Letterbin uses Public/Private key cryptography for it’s addressing of the email address and bin ID.
For this we use the secp256k1 scheme (similar to Bitcoin) with ECDH.
Email addresses are constructed by:
RIPEMD160(SHA256(public)), base16’d and truncated to a length of 8 alpha numeric characters (due to possible collisions this is recalculated if a match is found within Redis). Base16 was choosen due to case-insensitivity. For example, internally if an email is received with the address:
1234ABCD@letterb.in it is lowercased to:
The corresponding private key is Base58 encoded and used as the unique URL for the mailbox.
When requesting this address, this Base58 encoded value is decoded, then the public facing email address is reconstructed and looked up in the Redis data store. The private key is only kept in the URL and in transit (over TLS) and is not stored within Redis - this is why you must keep hold of it as it acts as your key.
Finally, here’s the scan of the site from securityheaders.io.
And for the mailserver from ssl-tools.net.