What is websocket.email?

websocket.email is a simple service for subscribing to throw away email addresses programatically or via the command line.

What problem does that solve?

What does it look like to use?


const WebSocket = require('ws');

const ws = new WebSocket('wss://api.websocket.email/v1/subscribe', {
  headers: {Token: "YOU_API_TOKEN", SubscribeTo: "foo@websocket.email"},

ws.on('message', function incoming(data) {
  // triggered whenever you send an email for foo@websocket.email.
  var email = JSON.parse(data);

Web browser

function init() { 
    websocket = new WebSocket("wss://api.websocket.email/v1/subscribe?Token=YOUR_API_TOKEN&SubscribeTo=foo");

    websocket.onmessage = function(evt) {
        var email = JSON.parse(evt.data);

window.addEventListener("load", init, false);


ch, cleanup, err := websocketemail.WaitForEmail("YOUR_API_TOKEN", "foo@websocket.email")
if err != nil {
defer cleanup()

select {
case email, ok := <-ch:
    if !ok {
        panic("unable to wait for email!")
    fmt.Printf("Got email: %#v", email)
case <-time.After(20 * time.Second):
    panic("email was not recieved after 20 seconds!")

Command line

How do I use it?

Get an API token and then:

Where do I get an API token?

Get a free API token that expires in 48 hours...

Purchase an API token that lasts 1 year...

What are the restrictions on a token?

What is the API?

Open a websocket connection to wss://api.websocket.email/v1/subscribe with the one of the following set:

If the specified emailed address does not contain an '@' symbol, '@websocket.email' will be assumed by the server.

On error the api may return the following HTTP status codes:

On success a websocket connection is established which will send json objects containing the parsed contents of any email under 512Kb sent to the specified address while the websocket was open.

The parsed JSON emails have the following format:

  To                string // recipient of the message.
  From              string // sender of the message.
  Subject           string // subject of the message.
  ContentType       string // content type of body if mail headers.
  Body              string // raw body of the email. 

More fields may be added in the future, but the current fields may be considered stable.

How private is this?

We will:

However, you should probably also:

What guarantees are there about uptime?

No guarantees, but best effort will be made to keep the service running 24/7 as it is in use for health checks and tests for other services. Planned downtime will be at 1 A.M. UTC when needed to enhance the service.

Are there refunds?

Yes, tokens younger than 24 hours can be refunded, though you should test with a free token before purchasing a token.

Refund a token...

What if I need help?

Contact websocketemail@codenegative.services