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.


Create directory for example code
$ mkdir websocket-example
$ cd websocket-example
Create package.json file with the following contents
  "name": "mailsac-node-websocket-example",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  "keywords": [],
  "author": "",
  "license": "MIT",
  "dependencies": {
    "ws": "^2.2.3"
Install required node packages
npm install
Create example.js file with the following contents
const WebSocket = require('ws');
const log = console.log; // eslint-disable-line

// Mailsac uses secure WebSockets. This is the WebSocket API base endpoint.
const BASE_URL = 'wss://';

// In this example, we pull the username and API key from environment variables.
// You could also hardcode the credentials, or use a package like node-config for managing them.
const username = process.env.MAILSAC_USER;
const apiKey = process.env.MAILSAC_KEY;
// List the addresses you want to receive messages for.
// You MUST have WebSocket forwarding turned on for the addresses!
const listenAddresses = process.env.ADDRESSES;

const urlParams = '?_id=' + username + '&key=' +apiKey+ '&addresses=' + listenAddresses;

log('attempting to open WebSocket to', BASE_URL + urlParams);
const ws = new WebSocket(BASE_URL + urlParams);

ws.on('open', function () {
  log('WebSocket opened');

ws.on('error', function (err) {
  log('connection error', err);

ws.on('message', function (data) {
Set environmental variables
export MAILSAC_USER='your mailsac username / _id';
export MAILSAC_KEY='your mailsac api key';
export ADDRESSES=','

Launch WebSocket Example

Launch the node program
node example.js
Expected output
attempting to open WebSocket to wss://
WebSocket opened

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.

Example message received over WebSocket
  "_id": "8mryf3viZQpWLX7E8SUzI3a5rEwg-0",
  "to": [
      "address": "",
      "name": ""
  "from": [
      "address": "",
      "name": ""
  "subject": "This is a subject",
  "inbox": "",
  "originalInbox": "",
  "domain": "",
  "received": "2020-06-23T01:33:13.790Z",
  "raw": "Received: from by frontend1-172-31-29-224 via with HTTP id 8ml9bOrEQ7J_0VMd0vjPULgc for ; Tue Jun 23 2020 01:33:13 GMT+0000 (Coordinated Universal Time)\nReceived: from\n\tsmtp-in2-172-31-42-57 via (proxy)\n\twith SMTP id 8ml9bOrEQ7J_0VMd0vjPULgc\n\tfor ; Tue, 23 Jun 2020 01:33:13 UTC\nX-Mailsac-Whitelist:,,\nX-Mailsac-Inbound-Version: 7463aab\nDKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;;\n q=dns/txt; s=mailsacrelay;\n bh=r0Rk73qDq89EuDZsfA4VqbZ/rqPclpo6FwUp6HTtsgg=;\n h=from:subject:to:mime-version:content-type:list-unsubscribe;\n b=C7leDzbCghwRfubINLbVmzTiecO/nA7zEsX0xuFJ9D8om617iGcD6q7CGysMu8jXcohxeeINI\n i2GvfKq2L7sXNPPFwBsnjGvIL8mJQYHWI+FEG3+TCnTc7ZRavKmQPAJl3B2k9QroWp5s2RyCdpJ\n vX+qjcoo7zwld6R2+C6Kmz4=\nContent-Type: multipart/alternative;\n boundary=\"----sinikael-?=_1-15928759930350.8681360034141601\"\nReceived: from frontend1-172-31-29-224 ([]) with HTTP by\n cranberry; Mon Jun 22 2020 21:33:12 GMT-0400 (Eastern Daylight Time)\nReceived: from ruffrey ( ([]) with HTTP id\n fe-vlp0jxneoa8 by frontend1-172-31-29-224 ([]);\n 2020-06-23T01:33:12.177Z\nFrom:\nTo:\nSubject: This is a subject\nMessage-ID: <>\nList-Unsubscribe: \nDate: Tue, 23 Jun 2020 01:33:13 +0000\nMIME-Version: 1.0\n\n------sinikael-?=_1-15928759930350.8681360034141601\nContent-Type: text/plain\nContent-Transfer-Encoding: 7bit\n\nHere's some message text.\n\nWe are testing web sockets.\n\n------sinikael-?=_1-15928759930350.8681360034141601\nContent-Type: text/html\nContent-Transfer-Encoding: 7bit\n\n Here's some message text.\n\nWe are testing web sockets.\n \n------sinikael-?=_1-15928759930350.8681360034141601--",
  "size": 1697,
  "rtls": true,
  "ip": "",
  "spam": 0.014,
  "headers": {
    "received": [
      "from by frontend1-172-31-29-224 via with HTTP id 8ml9bOrEQ7J_0VMd0vjPULgc for ; Tue Jun 23 2020 01:33:13 GMT+0000 (Coordinated Universal Time)",
      "from smtp-in2-172-31-42-57 via (proxy) with SMTP id 8ml9bOrEQ7J_0VMd0vjPULgc for ; Tue, 23 Jun 2020 01:33:13 UTC",
      "from frontend1-172-31-29-224 ([]) with HTTP by cranberry; Mon Jun 22 2020 21:33:12 GMT-0400 (Eastern Daylight Time)",
      "from ruffrey ( ([]) with HTTP id fe-vlp0jxneoa8 by frontend1-172-31-29-224 ([]); 2020-06-23T01:33:12.177Z"
    "x-mailsac-whitelist": ",,",
    "x-mailsac-inbound-version": "7463aab",
    "dkim-signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;; q=dns/txt; s=mailsacrelay; bh=r0Rk73qDq89EuDZsfA4VqbZ/rqPclpo6FwUp6HTtsgg=; h=from:subject:to:mime-version:content-type:list-unsubscribe; b=C7leDzbCghwRfubINLbVmzTiecO/nA7zEsX0xuFJ9D8om617iGcD6q7CGysMu8jXcohxeeINI i2GvfKq2L7sXNPPFwBsnjGvIL8mJQYHWI+FEG3+TCnTc7ZRavKmQPAJl3B2k9QroWp5s2RyCdpJ vX+qjcoo7zwld6R2+C6Kmz4=",
    "content-type": "multipart/alternative; boundary=\"----sinikael-?=_1-15928759930350.8681360034141601\"",
    "from": "",
    "to": "",
    "subject": "This is a subject",
    "message-id": "<>",
    "list-unsubscribe": "",
    "date": "Tue, 23 Jun 2020 01:33:13 +0000",
    "mime-version": "1.0"
  "text": "Here's some message text.\n\nWe are testing web sockets.\n",
  "html": "<div>Here's some message text.\n\nWe are testing web sockets.</div>\n",
  "via": ""

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.