API

Note: Throughout this document, replace :id and :bin etc with your values

Sections

Creating a new mailbox

You can either visit the mail site address at: https://letterbin.io or send off a request to:

https://letterbin.io/json

Which will return a payload like:

Where :bin_public_id is for example xyz in xyz@letterbin.io and :bin is the private ID of the bin.

The Mailbox

Requesting the following will give you a JSON representation of the mailbox:

https://letterbin.io/m/:bin/json

Sample response:

Likewise, you can request an individual emails’ body HTML using the following address:

https://letterbin.io/m/:bin/:id/body

Note: :id is returned in the JSON response above per email. attached: true under 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:

https://letterbin.io/m/:bin/stream

An example request with cURL would be:

curl https://letterbin.io/m/:bin/stream

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://letterbin.io/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:

https://letterbin.io/raw_mime/:raw_mime_hash

:raw_mime_hash is returned in the JSON response of the mailbox.

Attachments

Attachment URLs are made up of:

https://letterbin.io/attachments/:attachment_hash

You can download a single attachment with (remember, replace :bin with your bin’s ID):

You can get jq here.

Viewing the body of an email

You can fetch the body part of an email at this address:

https://letterbin.io/m/:bin/:id/body

:id can be found by first querying your bin’s JSON representation:

https://letterbin.io/m/:bin/json

Look for id which is a UUIDv4 identifier.

You can also fetch the embellished version (which includes some additional styling) by adding ?embellished to the URL:

https://letterbin.io/m/:bin/:id/body?embellished

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@letterbin.io it is lowercased to: 1234abcd@letterbin.io.

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.