From 92fa7a5d1a15a50cab3f72c0ec958db0735118f5 Mon Sep 17 00:00:00 2001
From: Veer Singh <digitalizedveer@gmail.com>
Date: Fri, 21 Aug 2026 22:05:14 -0700
Subject: [PATCH] docs(websockets): fix event type check for incoming messages

tldr; the WebSockets documentation incorrectly checks `event.type` for the value `"message_received"`

---
Right now, the WebSockets documentation checks if `event.type` equals `"message_received"`. In contrast, the API and SDK send `type: "event"` with `event_type: "message.received"`. This example code runs fine, but as a side effect ends up skipping incoming email events since the event branch is never reached.

This PR updates the code examples, doc comments, and overly strict type annotations across the WebSockets overview.

---

### Comparison

* What the WebSocket Docs check:

  ```js
  if (event.type === "message_received") { ... }
  ```

* What the server actually sends:

  ```json
  { "type": "event", "event_type": "message.received", ... }
  ```

### Changes

1. Fixed five checks across code and documentation to correctly use `event.type === "event" && event.eventType === "message.received"`.
1. Removed annotations on message handler to remove compilation errors.
1. Corrected the Message Properties table and code to use the correct `from`.
1. Removed two unused `AgentMail` imports.
---
 fern/pages/websockets.mdx | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/fern/pages/websockets.mdx b/fern/pages/websockets.mdx
index 5f7a9566..e8818833 100644
--- a/fern/pages/websockets.mdx
+++ b/fern/pages/websockets.mdx
@@ -123,7 +123,7 @@ The TypeScript SDK provides a WebSocket client with automatic reconnection.
 ### Basic Usage
 
 ```typescript
-import { AgentMailClient, AgentMail } from "agentmail";
+import { AgentMailClient } from "agentmail";
 
 const client = new AgentMailClient({
   apiKey: process.env.AGENTMAIL_API_KEY,
@@ -143,11 +143,11 @@ async function main() {
     });
   });
 
-  socket.on("message", (event: AgentMail.Subscribed | AgentMail.MessageReceivedEvent) => {
+  socket.on("message", (event) => {
     if (event.type === "subscribed") {
       console.log("Subscribed to:", event.inboxIds);
-    } else if (event.type === "message_received") {
-      console.log("New email from:", event.message.from_);
+    } else if (event.type === "event" && event.eventType === "message.received") {
+      console.log("New email from:", event.message.from);
       console.log("Subject:", event.message.subject);
     }
   });
@@ -193,7 +193,7 @@ function useAgentMailWebSocket(apiKey: string, inboxIds: string[]) {
       });
 
       socket.on("message", (event) => {
-        if (event.type === "message_received") {
+        if (event.type === "event" && event.eventType === "message.received") {
           setLastMessage(event);
         }
       });
@@ -320,7 +320,7 @@ The `event.message` object contains:
 | `inbox_id` | `inboxId` | Inbox that received the email |
 | `message_id` | `messageId` | Unique message ID |
 | `thread_id` | `threadId` | Conversation thread ID |
-| `from_` | `from_` | Sender email address |
+| `from_` | `from` | Sender email address |
 | `to` | `to` | Recipients list |
 | `subject` | `subject` | Subject line |
 | `text` | `text` | Plain text body |
@@ -355,7 +355,7 @@ async def main():
 
 **TypeScript:**
 ```typescript
-import { AgentMailClient, AgentMail, AgentMailError } from "agentmail";
+import { AgentMailClient, AgentMailError } from "agentmail";
 
 const client = new AgentMailClient({
   apiKey: process.env.AGENTMAIL_API_KEY,
@@ -372,8 +372,8 @@ async function main() {
       });
     });
 
-    socket.on("message", (event: AgentMail.MessageReceivedEvent) => {
-      if (event.type === "message_received") {
+    socket.on("message", (event) => {
+      if (event.type === "event" && event.eventType === "message.received") {
         processEmail(event.message);
       }
     });
@@ -430,7 +430,7 @@ Copy one of the blocks below into Cursor or Claude for WebSockets in one shot.
    *
    * const socket = await client.websockets.connect();
    * socket.on("open", () => socket.sendSubscribe({ type: "subscribe", inboxIds: [...] }));
-   * socket.on("message", (e) => { if (e.type === "subscribed") ...; if (e.type === "message_received") ... });
+   * socket.on("message", (e) => { if (e.type === "subscribed") ...; if (e.type === "event" && e.eventType === "message.received") ... });
    * socket.on("close" | "error", ...);
    */
   import { AgentMailClient } from "agentmail";
@@ -442,7 +442,7 @@ Copy one of the blocks below into Cursor or Claude for WebSockets in one shot.
     socket.on("open", () => socket.sendSubscribe({ type: "subscribe", inboxIds: ["agent@agentmail.to"] }));
     socket.on("message", (e) => {
       if (e.type === "subscribed") console.log(e.inboxIds);
-      if (e.type === "message_received") console.log(e.message.subject);
+      if (e.type === "event" && e.eventType === "message.received") console.log(e.message.subject);
     });
   }
   main().catch(console.error);