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?

• Automate integration tests that require email without setting up accounts, mocks, smtp servers or other boring stuff.
• Avoid fumbling with email accounts while developing email related software.
• Write automated health checks for your email workflows.
• Make email triggered gizmos (great with forwarding rules).
• Use your imagination!

What does it look like to use?

Node.js

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);
  console.log(email["From"]);
  console.log(email["Subject"]);
});

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);
        console.log(email["From"]);
        console.log(email["Subject"]);
    };
}

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

Go

ch, cleanup, err := websocketemail.WaitForEmail("YOUR_API_TOKEN", "foo@websocket.email")
if err != nil {
    panic(err)
}
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:

• Use the open source command line client.
• Use the one of the official libraries.
• Write your own code to use the (tiny) API.

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?

• Only 5 concurrent subscriptions can be done with a single token.
• Emails exceeding 512Kb may be rejected entirely.

What is the API?

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

• HTTP Headers:
  • Token: YOUR_API_TOKEN
  • SubscribeTo: EMAIL@websocket.email
• HTTP Basic Auth:
  • Username: YOUR_API_TOKEN
  • Password: EMAIL@websocket.email
• HTTP Get Parameters:
  • Token: YOUR_API_TOKEN
  • SubscribeTo: EMAIL@websocket.email

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:

• 401 Unauthorized - Your Token header value is expired, incorrect or missing.
• 429 Too Many Requests - More than 5 websocket subscriptions are open for the current token.
• 503 Service Unavailable - The server is currently down for maintenance or overloaded and applying back pressure.
• Other unspecified status codes may be possible if the websocket creation fails.

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:

• Keep the email addresses used for subscriptions a secret.
• Have TLS encryption avaliable on our smtp server.
• Discard email contents after delivery.

However, you should probably also:

• Generate random long throwaway emails to prevent people guessing your test addresses, e.g. 4c918d7e021073139abb75d4e4f9cd0edb374df1@websocket.email
• Not send any data too sensitive or critical through websocket.email without understanding the risks.

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