James - Logo

Email testing with Letterbin

Letterbin is a new service to allow easy end-to-end testing of email which is language and service agnostic. In this article we’ll walk through some of it’s features and what you can do with it!

Locally testing email is great and there are tools to handle that, but, what if we could do a complete integration test for example?

Letterbin’s main features include:

Getting started…

To get started, head over to: letterbin.io and click on ‘Take me to my inbox!’

You’ll be presented with the mailbox which will look similar to this:

Mailbox - Letterbin

Note: You may be promoted to allow notifications - these are simply notifications when new messages come in

You’ll notice that the address bar will contain a long URL. The address itself is the key to accessing the mailbox as there are no user logins on Letterbin. Make sure you make a note of that address by bookmarking the page if you would like to continue to use the same mailbox later ☺️

Ok, lets get started. You will notice an email address on the right pane. This will serve as your test email address, yours will be different to the one in the screenshot above - that’s a good thing!

Grab that address and send an email to it… got it? Good… it should look a little like this:

Email - Letterbin

Here you can see the subject (on the left and above the email body) and, the main body of the email.

You’ll also notice that HTML is selected and, for this email, there is a Text version too…

Clicking on ‘Show headers’ will reveal headers from the email.

So, that’s basically the mailbox view. Next up is the API…

API

At the top right of the screen you will see a ‘{ View as JSON }’ link. When you click that you’ll be presented with a JSON view of the mailbox.

Each email will be listed in turn along with headers, attachments etc. Here’s an example response:

[
  {
    "to": "2LrV4qq@letterbin.io",
    "text": "The text version of the email if it exists or an empty string",
    "subject": "Test",
    "received": "2016-04-29T14:26:24Z",
    "raw_mime": "raw_mime/bf7900f6d3077859ba649ad5b4556512e8de7fc…",
    "original_html": "Unmodified HTML from the email OR the raw text version (liable to change)",
    "id": "a3e2b1e0-cd13-48a8-bd51-abcf5c99f137",
    "html": "Modified HTML of the email - all attachments that were inlined are changed to <img> tags etc",
    "headers": [
      [ "header", "value" ],
      […]
    ],
    "attachments": [
        {
          "mime_type": "image/png",
          "filename": "letterbin.png",
          "data": "attachments/bf7900f6d3077859ba649ad5b4556512e8de7fc…",
          "attached": true
        }
      ]
    },
    //…
  }
]

Further details of the endpoints and formats are available in the docs.

Testing example

One of the things, maybe the main thing, you’d want to use this for is testing.

Here’s a brief example in Elixir:

defmodule EmailTest do
  use ExUnit.Case, async: true

  setup do

    # You could add your code to send the email here for example...

    response = HTTPoison.get!(System.get_env("EMAIL_TEST_ENDPOINT"))
    email = response.body
            |> Poison.decode!
            |> List.last
  end

  test "subject is correct", email,         do: assert email["subject"] == "Hi!"
  test "that I have no attachments", email, do: assert length(email["attachments"]) == 0
end

This is fairly trivial but hopefully will get the ball rolling!

Other fun things…

Maybe you would like to stream the mailbox in the terminal to see any new emails come in and limit the output to just the Subject?

Easy; all you need to run is the following (remember to replace the unique mailbox address with your address…):

$ curl -s https://letterbin.io/m/F3hQQBRYX8xnX2ZLFXLr2KrdAzPmKeRNd8MBTLxnupUA/stream --no-buffer | \
 jq --unbuffered --raw-output '.subject'

Ok, you will need jq installed - grab that here: https://jqlang.github.io/jq but you get the idea 🙂

There are more examples and details on the different endpoints etc in the docs.