WebSocket

Subscribe to an inbox over a persistent WebSocket to receive new messages in real time. Available on Startup plan and above. Each push event counts as one request toward your monthly quota.

Connection URL

wss://api2.freecustom.email/v1/ws?api_key=fce_xxx&mailbox=addr@domain.com

Query mailbox is optional — omit to subscribe to all registered inboxes.

Connection limits per plan

Startup: 5 concurrent · Growth: 20 · Enterprise: 100. Requires Startup plan or higher.

Server events

On connect: { "type": "connected", "plan": "startup", "subscribed_to": [...], "max_connections": 5, "current_connections": 2 }

New email: { "type": "new_message", "inbox": "...", "message": { "id", "from", "subject", "date", "has_attachment", "otp", "verification_link" } }

Heartbeat: Server sends { "type": "ping" } every 30s; client responds with { "type": "pong" }.

Close codes

4001 — Invalid/missing API key · 4003 — Plan too low · 4004 — Inbox not registered · 4029 — Connection limit reached. Error payload: { "type": "error", "code": "...", "message": "...", "upgrade_url": "..." }

Node.js example (ws)

const WebSocket = require("ws");
const ws = new WebSocket(
  "wss://api2.freecustom.email/v1/ws?api_key=" + process.env.FCE_API_KEY + "&mailbox=test@ditapi.info"
);
ws.on("message", (data) => console.log(JSON.parse(data)));
ws.on("open", () => ws.send(JSON.stringify({ type: "pong" })));

Python example (websockets)

import asyncio
import websockets
import json

async def main():
    uri = "wss://api2.freecustom.email/v1/ws?api_key=YOUR_KEY&mailbox=test@ditapi.info"
    async with websockets.connect(uri) as ws:
        async for msg in ws:
            data = json.loads(msg)
            if data.get("type") == "ping":
                await ws.send(json.dumps({"type": "pong"}))
            else:
                print(data)

asyncio.run(main())