WebSocket connection drops keep killing your agent's email

Your agent processed 340 emails on Monday. On Tuesday, it processed zero. The logs showed nothing wrong. The WebSocket connection had dropped sometime around 2 AM, the reconnection logic never fired, and your agent sat idle listening to a dead socket for nine hours before anyone noticed.

This is the most common failure mode in agent email pipelines. It's also the hardest to detect because nothing actually errors out.

I've spent months debugging this pattern across agent deployments. It always looks the same: a long-lived WebSocket connection dies without triggering onclose, the agent assumes it's still receiving events, and inbound emails pile up unprocessed on the server. If you're done babysitting socket connections, get your agent an inbox that doesn't depend on WebSocket uptime. LobsterMail handles delivery at the infrastructure level, so a dropped socket never means a dropped email.

Why WebSocket connections drop: root causes at a glance#

These are the seven most common reasons WebSocket connections fail in production:

1. NAT gateway timeouts silently expire idle connections after 30-60 seconds of inactivity
2. Missing application-level heartbeats leave both sides unaware the connection is dead
3. Reverse proxies like nginx close WebSocket connections when the default proxy_read_timeout (60 seconds) expires
4. TLS certificate expiry or mismatch triggers intermittent connection resets
5. Server-side idle timeout thresholds close connections that haven't exchanged data recently
6. Half-open TCP state leaves one side believing the connection is alive while the other has already torn it down
7. No event queue behind the WebSocket means messages sent during a drop vanish permanently

For agent email pipelines, cause number seven is the one that actually costs you money. The first six are fixable with configuration tweaks. The seventh requires a different architecture entirely.

Silent drops vs clean closes#

A normal WebSocket close involves a close frame (opcode 0x8). Both sides acknowledge the shutdown, and your onclose handler fires. Your code knows the connection ended and can reconnect within milliseconds.

A silent drop skips all of that. The TCP connection dies at the network layer without either endpoint sending a close frame. Your client's socket object still exists. readyState still returns OPEN. But nothing flows through the connection anymore. This happens when a NAT gateway expires the connection mapping, when a load balancer reclaims an idle slot, or when the remote server crashes without performing a graceful shutdown.

The practical difference is simple: a clean close triggers your reconnection logic. A silent drop triggers nothing. Your agent stops receiving email and neither the agent nor your monitoring has any indication that something went wrong.

Why agent email breaks differently#

A chat application with 10,000 connected users can tolerate scattered WebSocket drops. Users notice the lag, refresh the page, and reconnect. The lost messages are usually just typing indicators or presence updates.

Agent email pipelines have a different failure profile. An agent processing inbound email typically has one connection, running unattended for days or weeks. There's no human watching the interface. There's no refresh button. When that single WebSocket drops silently, the agent continues running its main loop, checking a socket that will never produce another event.

Meanwhile, emails keep arriving at the mail server. They accumulate in a queue the agent can't see because it's listening to a dead connection. By the time someone discovers the problem (usually when a customer complains about a missed reply), hundreds of messages may be sitting in a server-side buffer that your agent never polled.

If your email delivery depends on WebSocket events, you've coupled email reliability to network reliability. Those two things have very different failure modes. We covered the tradeoffs between real-time push and periodic retrieval in our guide on webhooks vs polling: how your agent should receive emails.

WebSocket vs SSE vs polling for agent email#

If WebSocket connections are this fragile for agent workloads, should you use a different transport? Here's how the three main approaches compare:

SSE handles reconnection more gracefully than WebSocket because the protocol includes a retry mechanism and a Last-Event-ID header. When an SSE connection drops, the client automatically reconnects and tells the server which event it last received. The server can then replay anything that was missed.

But all three approaches share the same fundamental weakness for email agents: they put the delivery guarantee on the client. If your agent is down, sleeping, or restarting during a deploy, events accumulate somewhere. That "somewhere" may not survive a restart, and your agent has no way to know what it missed.

Queue-backed delivery: the actual fix#

The real solution isn't choosing between WebSocket, SSE, or polling. It's making the transport choice irrelevant to delivery guarantees.

A queue-backed email architecture persists every inbound email before attempting to notify your agent. The notification channel (WebSocket, webhook, polling, whatever you prefer) is just a signal that new mail exists. If the signal gets lost, the email doesn't. Your agent calls receive() when it's ready, and it gets everything that arrived since its last check.

This is how LobsterMail works. When an email hits your agent's inbox, it's stored immediately. Your agent retrieves messages through the SDK or a webhook callback. If your agent goes offline for an hour, the emails wait. If a webhook delivery fails, retries happen automatically. The storage layer and the notification layer are completely separate concerns with independent reliability guarantees.

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: 'Support Agent' });

// Emails are persisted server-side. receive() returns everything
// since your last retrieval, regardless of connection state.
const emails = await inbox.receive();

for (const email of emails) {
  console.log(email.subject, email.from);
}

No WebSocket to manage. No heartbeat interval to tune. No reconnection logic to debug at 3 AM. No silent drops to lose sleep over. The SDK makes an HTTP request and gets back whatever emails have arrived. If you want real-time push on top of that, add a webhook, but the webhook is a notification convenience, not the delivery mechanism itself.

If you're stuck with WebSocket-based email delivery#

If you're running infrastructure that requires WebSocket for email events and can't switch right now, three changes will catch most silent drops.

First, implement application-level heartbeats. Don't rely on TCP keepalive or WebSocket protocol-level pings alone. Send a custom ping message every 15 seconds from your client and expect a pong within 5 seconds. If you miss two consecutive pongs, tear down the connection and force a reconnect. Fifteen seconds is the right interval because most NAT gateways expire idle mappings between 30 and 120 seconds, and you need your heartbeat to arrive before that window closes.

Second, fix your reverse proxy configuration. If you're running nginx, set proxy_read_timeout to at least 3600 seconds for your WebSocket location block. The default 60-second value is the single most common cause of unexpected WebSocket termination in production.

location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

Third, add a reconciliation loop. Every five minutes, have your agent make a separate HTTP request to fetch any emails it might have missed. Compare the results against what came through the WebSocket. This catches every silent drop, including the ones your heartbeat logic misses.

That reconciliation loop is really just polling with more steps. If you find yourself building one on top of your WebSocket, it's worth asking whether the WebSocket is earning its keep. Before testing any of these changes in production, try testing agent email without hitting production to verify your reconnection logic handles edge cases cleanly.

The simpler path is letting infrastructure handle transport reliability for you. Set up a LobsterMail inbox for your agent and spend your time on what your agent actually does with its email, not on keeping the connection alive.