---
title: "Connect a web socket to wss://sock.mailsac.com/incoming-messages"
method: POST
path: "/custom_web_sockets"
tags: ["Web Sockets"]
---

# Connect a web socket to wss://sock.mailsac.com/incoming-messages

`POST /custom_web_sockets`

*Note: this does not work in Swagger UI. Visit https://sock.mailsac.com to test.*

You can receive email via web socket for private email addresses and custom domains.

To enable web socket forwarding:

* Addresses: Select *Edit* for the email address you want to forward.
Then check the checkbox for web socket forwarding, and save.
* Custom Domains: Select *Manage* for the domain and click the *Forwarding* tab. Toggle
the *Enable Web Sockets* option.

Note: Web socket forwarding is **not enabled by default.**

### Web Socket Examples

#### Web Socket Test Page

https://sock.mailsac.com

Receive emails in your web browser.

Experiment with the web socket gateway in realtime.

#### Web Socket Node.js

Listen for Mailsac emails via websocket in this tiny Node.js example app.

https://github.com/ruffrey/mailsac-node-websocket-example

### Web Socket Connection Endpoint

The web socket endpoint is `wss://sock.mailsac.com/incoming-messages`

Example:

> wss://sock.mailsac.com/incoming-messages?key=k_e9bPnd2adexample&addresses=jeff@mailsac.com,asdf-outbound.mailsac.com

> First frame:

```
{
  "status": 200,
  "msg": "Listening",
  "addresses": [
    "jeff@mailsac.com"
  ],
  "domains": [
    "asdf-outbound.mailsac.com"
  ]
}
```

All web socket messages are JSON. After parsing the JSON, there will be a status field with
an HTTP status code (usually 200).

An email coming over the web socket will also have an email property, and its value will be
the same as the messages REST API, plus some additional fields.

## Other responses

- `101` — Successful web socket upgrade

---

[API](https://skmtc.dev/mailsac/apis/mailsac-api-specification.md) · [All operations](https://skmtc.dev/mailsac/apis/mailsac-api-specification/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mailsac/mailsac-api-specification/revisions/5f8b55c76229/schema)