For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
contact@agentmail.ccDiscord
DocumentationAPI ReferenceKnowledge BaseChangelog
DocumentationAPI ReferenceKnowledge BaseChangelog
  • Get Started
    • Welcome
    • Introduction
    • Quickstart
  • Core Concepts
    • Inboxes
    • Messages
    • Threads
    • Drafts
    • Labels
    • Lists
    • Attachments
    • Pods
    • Permissions
  • Integrations
    • Agent Onboarding
    • Skills
    • MCP
    • CLI
    • Google ADK
    • OpenClaw
    • Replit
    • x402
    • MPP
    • LiveKit
    • Sim.ai
  • Guides
    • Sending & Receiving Email
    • IMAP & SMTP
    • Multi-Tenancy
  • Webhooks
    • Overview
    • Events
    • Setup Guide
    • Verifying Webhooks
  • WebSockets
    • Overview
    • Quickstart
  • Best Practices
    • Email Deliverability
    • Idempotency
  • Examples
    • Github Repo Agent
    • Auto Reply Agent
    • Smart Labeling Agent
    • Sales Agent (WebSocket)
    • Live AgentMail Examples
  • Resources
    • FAQ
    • Talon Reply Extraction
    • Community
    • Support
LogoLogo
contact@agentmail.ccDiscord
On this page
  • Copy for Cursor / Claude
  • SDK Examples
WebSockets

WebSockets Quickstart

Get started with real-time email event streaming

Was this page helpful?
Edit this page
Previous

Email Deliverability

Best practices for landing your emails in the inbox, not the spam folder.
Next
Built with

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for instant WebSocket setup.

1"""
2AgentMail WebSockets Quickstart — copy into Cursor/Claude.
3client.websockets.connect() → socket.send_subscribe(Subscribe(inbox_ids=[...])) → iterate socket for events.
4"""
5from agentmail import AgentMail, Subscribe, Subscribed, MessageReceivedEvent
6
7client = AgentMail()
8with client.websockets.connect() as socket:
9 socket.send_subscribe(Subscribe(inbox_ids=["my-agent@agentmail.to"]))
10 for event in socket:
11 if isinstance(event, Subscribed): print(f"Subscribed to {event.inbox_ids}")
12 elif isinstance(event, MessageReceivedEvent): print(f"Received from: {event.message.from_}")

SDK Examples

TypeScript
1import { AgentMailClient } from "agentmail";
2
3const client = new AgentMailClient();
4
5async function main() {
6 const socket = await client.websockets.connect();
7
8 socket.on("message", async (event) => {
9 if (event.type === "subscribed") {
10 console.log("Subscribed to", event.inboxIds);
11 } else if (
12 event.type === "event" &&
13 event.eventType === "message.received"
14 ) {
15 console.log(`Received message from: ${event.message.from}`);
16 }
17 });
18
19 await socket.waitForOpen();
20
21 socket.sendSubscribe({
22 type: "subscribe",
23 inboxIds: ["my-agent@agentmail.to"],
24 });
25}
26
27main();
Python
1from agentmail import AgentMail, MessageReceivedEvent, Subscribe, Subscribed
2
3client = AgentMail()
4
5with client.websockets.connect() as socket:
6 socket.send_subscribe(Subscribe(inbox_ids=["my-agent@agentmail.to"]))
7
8 for event in socket:
9 if isinstance(event, Subscribed):
10 print(f"Subscribed to {event.inbox_ids}")
11 elif isinstance(event, MessageReceivedEvent):
12 msg = event.message
13 print(f"Received message from: {msg.from_}")