Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time


A Websocket provides a unique way of monitoring the incoming email of a particular address. With a single persistent connection all content from an email address can be forward over the Websocket. This allows your application to be notified of an incoming emails as soon as it arrives. This helps reduce the number of API calls and reduces latency from when the email arrives and your application responds to it.

Want to see it in action? The WebSocket Test Page allows you to show how it works with no programming involved.

Configure Private Address for WebSocket

To use the Websocket feature a private email is required. Private addresses can be purchased individually as part of a API Developer Subscription.

Option 1: Reserve Private Address via API

The REST API is the easiest way to reserve a private address.

A simple HTTP POST will do. Make sure you have private address credits already, from a paid plan or addon purchase. in the example should be replaced with the email address you wish to reserve. If you use a custom domain, different than, you must have the domain configured with DNS records to delivery mail to Mailsac.

curl -X POST -H "Mailsac-Key: YOUR_API_KEY_HERE"

Next, configure the private address for web socket publishing:

curl -H 'Mailsac-Key: YOUR_API_KEY_HERE' -X PUT -d '{"enablews": true}'

Option 2: Reserve Private Address in the Dashboard

  1. Sign in to your Mailsac account.

  2. Select Manage Email Addresses from the dropdown.

  3. Select Add Email Address from Manage Email Addresses

  4. Fill in the desired email address and optionally add a note.

  5. Select Manage Email Addresses and choose settings next to the email address you want to configure for Websocket.

  6. Check the box to "Forward all incoming emails via web socket"


Receive Mail Using a WebSocket

Receiving mail from a Websocket allows for interacting with incoming email in near real time.

WebSockets are a powerful tool allowing you to end-to-end test your application's email delivery systems, or respond to incoming mail in sophisticated ways - without having to setup a mail server or mess around with SMTP code.



Launch WebSocket Example

Now, when an email messages are delivered to, they will also be sent to your WebSocket. Try sending a message - it will be parsed into JSON and logged to the console.

The WebSocket message body is nearly identical to the Messages REST API with the addition of the key "raw" which contains the entire raw email message received over SMTP.

Try It

Visit the Web Socket Test Page and receive emails in your web browser, without writing any code.


If the WebSocket is not working, additional debugging information is available in :ref:`doc_recent_activity`.