agentmail 0.3.7 → 0.3.8

package/dist/llms-full.txt

@@ -171,6 +171,146 @@ Follow this guide to make your first AgentMail API request and create a new
 email inbox.
 ------------
 
+## Quickest start
+
+<CodeBlocks>
+  ```bash title="Python"
+  pip install agentmail
+  ```
+
+  ```bash title="TypeScript"
+  npm install agentmail
+  ```
+</CodeBlocks>
+
+Get your API key from the [Console](https://console.agentmail.to) and replace `am_...` in the code below.
+
+<CodeBlocks>
+  ```python title="Python"
+  from agentmail import AgentMail
+
+  client = AgentMail(api_key="am_...")
+  inbox = client.inboxes.create()
+  client.inboxes.messages.send(inbox.inbox_id, to="user@example.com", subject="Hello", text="Hello from my agent!")
+  ```
+
+  ```typescript title="TypeScript"
+  import { AgentMailClient } from "agentmail";
+
+  (async () => {
+    const client = new AgentMailClient({ apiKey: "am_..." });
+    const inbox = await client.inboxes.create();
+    await client.inboxes.messages.send(inbox.inboxId, { to: "user@example.com", subject: "Hello", text: "Hello from my agent!" });
+  })();
+  ```
+</CodeBlocks>
+
+## Copy for Cursor / Claude
+
+Copy one of the blocks below into Cursor or Claude for a complete, working AgentMail integration. Each block includes setup, API reference, error handling, rate limiting, and idempotency guidance.
+
+<CodeBlocks>
+  ```python title="Python"
+  """
+  AgentMail Python Quickstart — copy into Cursor/Claude for instant setup.
+
+  Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
+
+  API reference:
+  - inboxes.create(username?, domain?, display_name?, client_id?) — client_id for idempotent retries
+  - messages.send(inbox_id, to, subject, text, html?, cc?, bcc?, reply_to?, attachments?)
+  - messages.list(inbox_id, limit?, page_token?, labels?) — receive emails; use extracted_text/extracted_html for reply content
+
+  Errors: SDK raises on 4xx/5xx. Inspect error.body.message or str(e).
+  Rate limit: 429 with Retry-After header. Implement exponential backoff for retries.
+  Idempotency: Pass client_id to inboxes.create() to safely retry without duplicates.
+  """
+  import os
+  from dotenv import load_dotenv
+  from agentmail import AgentMail
+
+  load_dotenv()
+  client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
+
+  # Create inbox (client_id enables safe retries)
+  inbox = client.inboxes.create(client_id="my-agent-inbox-v1")
+
+  # Send email
+  try:
+      client.inboxes.messages.send(
+          inbox.inbox_id,
+          to="recipient@example.com",
+          subject="Hello from AgentMail",
+          text="Plain text body",
+          html="<p>HTML body</p>",
+      )
+  except Exception as e:
+      # Handle validation, not found, rate limit (429), etc.
+      print(f"Send failed: {e}")
+      raise
+
+  # Receive messages
+  for msg in client.inboxes.messages.list(inbox.inbox_id, limit=10).messages:
+      print(msg.subject, msg.extracted_text or msg.text)
+  ```
+
+  ```typescript title="TypeScript"
+  /**
+   * AgentMail TypeScript Quickstart — copy into Cursor/Claude for instant setup.
+   *
+   * Setup: npm install agentmail dotenv. Set AGENTMAIL_API_KEY in .env.
+   *
+   * API reference:
+   * - inboxes.create({ username?, domain?, displayName?, clientId? }) — clientId for idempotent retries
+   * - messages.send(inboxId, { to, subject, text, html?, cc?, bcc?, replyTo?, attachments? })
+   * - messages.list(inboxId, { limit?, pageToken?, labels? }) — receive; use extractedText/extractedHtml for reply content
+   *
+   * Errors: SDK throws on 4xx/5xx. Check error.body?.message.
+   * Rate limit: 429 with Retry-After header. Use exponential backoff for retries.
+   * Idempotency: Pass clientId to inboxes.create() to safely retry without duplicates.
+   */
+  import { AgentMailClient } from "agentmail";
+  import "dotenv/config";
+
+  const client = new AgentMailClient({
+    apiKey: process.env.AGENTMAIL_API_KEY!,
+  });
+
+  async function main() {
+    // Create inbox (clientId enables safe retries)
+    const inbox = await client.inboxes.create({
+      clientId: "my-agent-inbox-v1",
+    });
+
+    try {
+      await client.inboxes.messages.send(inbox.inboxId, {
+        to: "recipient@example.com",
+        subject: "Hello from AgentMail",
+        text: "Plain text body",
+        html: "<p>HTML body</p>",
+      });
+    } catch (error: unknown) {
+      // Handle validation, not found, rate limit (429), etc.
+      const msg = (error as { body?: { message?: string } })?.body?.message ?? String(error);
+      throw new Error(`Send failed: ${msg}`);
+    }
+
+    // Receive messages
+    const res = await client.inboxes.messages.list(inbox.inboxId, { limit: 10 });
+    for (const msg of res.messages) {
+      console.log(msg.subject, msg.extractedText ?? msg.text);
+    }
+  }
+
+  main();
+  ```
+</CodeBlocks>
+
+<Tip>
+  When receiving emails, messages include `extracted_text` and `extracted_html`
+  for reply content without quoted history.
+</Tip>
+
 This guide will walk you through installing the AgentMail SDK, authenticating with your API key, and creating your first email inbox.
 
 <Steps>
@@ -235,11 +375,10 @@ This guide will walk you through installing the AgentMail SDK, authenticating wi
       # Send Email
 
       client.inboxes.messages.send(
-      inbox_id="your-email@example.com",
-      to="contact@agentmail.to",
-      subject="Hello from AgentMail!",
-      text="This is my first email sent with the AgentMail API."
-
+        inbox.inbox_id,
+        to="your-email@example.com",
+        subject="Hello from AgentMail!",
+        text="This is my first email sent with the AgentMail API.",
       )
 
       ```
@@ -619,6 +758,8 @@ You can retrieve the details of any specific `Message` by providing its ID along
   ```
 </CodeBlocks>
 
+When receiving replies or forwards, use `extracted_text` or `extracted_html` for just the new content—quoted history is stripped automatically.
+
 ### Crafting Your Message: HTML, Text, and CSS
 
 When sending a `Message`, you can provide the body in two formats: `text` for a plain-text version and `html` for a rich, styled version.
@@ -1180,6 +1321,99 @@ This is where `Labels` become truly powerful. You can list `Threads`, `Messages`
 </Callout>
 
 
+***
+
+title: Lists
+subtitle: Filter emails by allowing or blocking specific addresses and domains.
+slug: lists
+description: >-
+Learn how to use Lists to control which email addresses and domains your
+agents can send to or receive from.
+-----------------------------------
+
+## What are Lists?
+
+`Lists` allow you to filter emails by allowing or blocking specific email addresses or domains. There are four list types based on two dimensions:
+
+* **Direction**: `send` or `receive`
+* **Type**: `allow` or `block`
+
+| List          | Description                                          |
+| ------------- | ---------------------------------------------------- |
+| Receive allow | Only accept emails from these addresses or domains   |
+| Receive block | Reject emails from these addresses or domains        |
+| Send allow    | Only send emails to these addresses or domains       |
+| Send block    | Prevent sending emails to these addresses or domains |
+
+Each entry can be either a full email address (e.g., `partner@example.com`) or an entire domain (e.g., `example.com`).
+
+## SDK examples
+
+### List entries
+
+Retrieve entries from a list with optional pagination.
+
+<CodeBlocks>
+  ```python title="Python"
+  entries = client.lists.list("receive", "allow", limit=10)
+  ```
+
+  ```typescript title="TypeScript"
+  const entries = await client.lists.list("receive", "allow", { limit: 10 });
+  ```
+</CodeBlocks>
+
+### Create entry
+
+Add an email address or domain to a list. The `reason` parameter is optional and available on block lists.
+
+<CodeBlocks>
+  ```python title="Python"
+  # allow list - no reason needed
+  client.lists.create("receive", "allow", entry="partner@example.com")
+
+  # block list - reason optional
+  client.lists.create("receive", "block", entry="spam@example.com", reason="spam")
+  ```
+
+  ```typescript title="TypeScript"
+  // allow list - no reason needed
+  await client.lists.create("receive", "allow", { entry: "partner@example.com" });
+
+  // block list - reason optional
+  await client.lists.create("receive", "block", { entry: "spam@example.com", reason: "spam" });
+  ```
+</CodeBlocks>
+
+### Get entry
+
+Retrieve a specific entry from a list by its email address or domain.
+
+<CodeBlocks>
+  ```python title="Python"
+  entry = client.lists.get("receive", "allow", entry="partner@example.com")
+  ```
+
+  ```typescript title="TypeScript"
+  const entry = await client.lists.get("receive", "allow", "partner@example.com");
+  ```
+</CodeBlocks>
+
+### Delete entry
+
+Remove an entry from a list.
+
+<CodeBlocks>
+  ```python title="Python"
+  client.lists.delete("receive", "allow", entry="partner@example.com")
+  ```
+
+  ```typescript title="TypeScript"
+  await client.lists.delete("receive", "allow", "partner@example.com");
+  ```
+</CodeBlocks>
+
+
 ***
 
 title: Attachments
@@ -1572,30 +1806,30 @@ title: Skills
 subtitle: Add AgentMail to AI coding assistants with the official skill
 slug: integrations/skills
 description: >-
-AgentMail's official skill for Moltbot, Claude Code, Cursor, and other AI
+AgentMail's official skill for OpenClaw, Claude Code, Cursor, and other AI
 assistants
 ----------
 
 ## Getting started
 
-AgentMail provides an official skill that can be installed on AI coding assistants and agents that support the [AgentSkills](https://skills.sh) format. This includes Moltbot, Claude Code, Cursor, Codex, and other compatible tools.
+AgentMail provides an official skill that can be installed on AI coding assistants and agents that support the [AgentSkills](https://skills.sh) format. This includes OpenClaw, Claude Code, Cursor, Codex, and other compatible tools.
 
 The skill is available at [skills.sh/agentmail-to/agentmail-skills/agentmail](https://skills.sh/agentmail-to/agentmail-skills/agentmail).
 
 ## Installation
 
-### Moltbot
+### OpenClaw
 
-Install the skill using the Moltbot CLI:
+Install the skill using the OpenClaw CLI:
 
 ```bash
-moltbot skills install agentmail-to/agentmail-skills/agentmail
+openclaw skills install agentmail-to/agentmail-skills/agentmail
 ```
 
-Or install via ClawdHub:
+Or install via ClawHub:
 
 ```bash
-clawdhub install agentmail
+npx clawhub@latest install agentmail
 ```
 
 ### Claude Code
@@ -1634,9 +1868,9 @@ Set the `AGENTMAIL_API_KEY` environment variable:
 export AGENTMAIL_API_KEY="your-api-key-here"
 ```
 
-### Moltbot configuration
+### OpenClaw configuration
 
-Add the API key to `~/.clawdbot/moltbot.json`:
+Add the API key to `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -1723,7 +1957,13 @@ The Model Context Protocol (MCP) is an open standard that enables AI application
 
 ### Setup
 
-To get started with the AgentMail MCP server, visit [mcp.agentmail.to](https://mcp.agentmail.to) for installation instructions and configuration details.
+Install with:
+
+```bash
+npx @smithery/cli@latest mcp add agentmail
+```
+
+Configure your API key when prompted. Get your key from the [AgentMail Console](https://console.agentmail.to). For more details, visit [mcp.agentmail.to](https://mcp.agentmail.to).
 
 ## Features
 
@@ -1748,25 +1988,25 @@ For detailed setup instructions and available tools, visit [mcp.agentmail.to](ht
 
 ***
 
-title: Openclaw
-subtitle: Give your Openclaw agent its own email inbox
+title: OpenClaw
+subtitle: Give your OpenClaw agent its own email inbox
 slug: integrations/openclaw
-description: AgentMail's Openclaw integration
+description: AgentMail's OpenClaw integration
 ---------------------------------------------
 
 ## Getting started
 
-Openclaw (formerly Moltbot) is an open-source AI personal assistant that runs on your own devices and integrates with messaging platforms like WhatsApp, Telegram, Discord, and Slack. By adding AgentMail to Openclaw, your agent gains the ability to send and receive emails, enabling two-way email conversations alongside your existing chat channels.
+OpenClaw (formerly Moltbot) is an open-source AI personal assistant that runs on your own devices and integrates with messaging platforms like WhatsApp, Telegram, Discord, and Slack. By adding AgentMail to OpenClaw, your agent gains the ability to send and receive emails, enabling two-way email conversations alongside your existing chat channels.
 
-There are two ways to integrate AgentMail with Openclaw: using the official AgentMail skill or creating a custom skill.
+There are two ways to integrate AgentMail with OpenClaw: using the official AgentMail skill or creating a custom skill.
 
 ## Option 1: Official AgentMail Skill (Recommended)
 
-The easiest way to add email capabilities to Openclaw is by installing the official AgentMail skill from [skills.sh](https://skills.sh/agentmail-to/agentmail-skills/agentmail). This skill is maintained by the AgentMail team and provides comprehensive email functionality.
+The easiest way to add email capabilities to OpenClaw is by installing the official AgentMail skill from [skills.sh](https://skills.sh/agentmail-to/agentmail-skills/agentmail). This skill is maintained by the AgentMail team and provides comprehensive email functionality.
 
 ### Installation
 
-Install the skill using the Openclaw CLI:
+Install the skill using the OpenClaw CLI:
 
 ```bash
 openclaw skills install agentmail-to/agentmail-skills/agentmail
@@ -1824,11 +2064,11 @@ You should see `agentmail` in the list of available skills.
 
 ## Option 2: Custom Skill
 
-For more control over the integration, you can create a custom AgentMail skill. Skills are directories containing a `SKILL.md` file with instructions for Openclaw.
+For more control over the integration, you can create a custom AgentMail skill. Skills are directories containing a `SKILL.md` file with instructions for OpenClaw.
 
 ### Create the skill directory
 
-Create a new skill in your Openclaw workspace:
+Create a new skill in your OpenClaw workspace:
 
 ```bash
 mkdir -p ~/.openclaw/skills/agentmail
@@ -1890,10 +2130,10 @@ curl -s -X POST -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
     "to": ["recipient@example.com"],
-    "subject": "Hello from Openclaw",
+    "subject": "Hello from OpenClaw",
     "text": "This email was sent by my AI assistant."
   }' \
-  https://api.agentmail.to/v0/inboxes/{inbox_id}/messages
+  https://api.agentmail.to/v0/inboxes/{inbox_id}/messages/send
 ```
 
 ### List messages in an inbox
@@ -1944,7 +2184,7 @@ You should see `agentmail` in the list of available skills.
 
 ## Example use cases
 
-Once AgentMail is integrated with Openclaw, you can ask your agent to:
+Once AgentMail is integrated with OpenClaw, you can ask your agent to:
 
 * "Create a new email inbox for my project"
 * "Check my inbox for new emails"
@@ -1954,9 +2194,9 @@ Once AgentMail is integrated with Openclaw, you can ask your agent to:
 
 ## Real-time email notifications
 
-For proactive email handling, you can combine AgentMail webhooks with Openclaw's webhook support. This allows Openclaw to notify you immediately when new emails arrive.
+For proactive email handling, you can combine AgentMail webhooks with OpenClaw's webhook support. This allows OpenClaw to notify you immediately when new emails arrive.
 
-1. Set up a webhook endpoint in Openclaw (see [Openclaw webhook documentation](https://docs.openclaw.ai/automation/webhook))
+1. Set up a webhook endpoint in OpenClaw (see [OpenClaw webhook documentation](https://docs.openclaw.ai/automation/webhook))
 
 2. Register the webhook with AgentMail:
 
@@ -1970,14 +2210,14 @@ curl -X POST -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
   https://api.agentmail.to/v0/webhooks
 ```
 
-Now Openclaw will be notified whenever a new email arrives, allowing it to proactively inform you or take action.
+Now OpenClaw will be notified whenever a new email arrives, allowing it to proactively inform you or take action.
 
 ## Resources
 
 * [Official AgentMail Skill](https://skills.sh/agentmail-to/agentmail-skills/agentmail)
 * [AgentMail API Reference](/api-reference)
-* [Openclaw Documentation](https://docs.openclaw.ai)
-* [Openclaw Skills Guide](https://docs.openclaw.ai/tools/skills)
+* [OpenClaw Documentation](https://docs.openclaw.ai)
+* [OpenClaw Skills Guide](https://docs.openclaw.ai/tools/skills)
 
 
 ***
@@ -2196,6 +2436,164 @@ Email is critical to identity and communication on the internet. Much of the con
 These are just a few select verticals, but we have seen AgentMail be effective in automating any email task across every function. If a human does it with email, it can be automated with AgentMail.
 
 
+***
+
+title: x402
+subtitle: Pay-per-use AgentMail with the x402 payment protocol
+slug: integrations/x402
+description: AgentMail's x402 integration for HTTP-native payments
+------------------------------------------------------------------
+
+## Getting started
+
+[x402](https://www.x402.org/) is an open payment protocol that enables HTTP-native payments. By integrating x402 with AgentMail, your agents can pay for API usage directly over HTTP without managing API keys or subscriptions.
+
+### Base URLs
+
+To authenticate with x402 instead of an API key, you must use the x402-specific base URLs below. These replace the default AgentMail base URLs and route requests through the x402 payment layer.
+
+| Protocol  | URL                     |
+| --------- | ----------------------- |
+| HTTP      | `x402.api.agentmail.to` |
+| WebSocket | `x402.ws.agentmail.to`  |
+
+### Prerequisites
+
+* A crypto wallet with USDC funds (EVM-compatible wallet on Base, or a Solana wallet)
+* Node.js installed
+
+### Install dependencies
+
+<CodeBlocks>
+  ```bash title="EVM"
+  npm install agentmail @x402/fetch @x402/evm viem
+  ```
+
+  ```bash title="Solana"
+  npm install agentmail @x402/fetch @x402/svm @solana/kit @scure/base
+  ```
+</CodeBlocks>
+
+### Quickstart
+
+<CodeBlocks>
+  ```typescript title="EVM"
+  import { privateKeyToAccount } from "viem/accounts";
+  import { x402Client } from "@x402/fetch";
+  import { ExactEvmScheme } from "@x402/evm/exact/client";
+
+  import { AgentMailClient } from "agentmail";
+
+
+  // setup x402 client
+
+  const PRIVATE_KEY = "0x...";
+
+  const signer = privateKeyToAccount(PRIVATE_KEY);
+
+  const x402 = new x402Client();
+  x402.register("eip155:*", new ExactEvmScheme(signer));
+
+
+  // setup AgentMail client
+
+  export const client = new AgentMailClient({ x402 });
+
+
+  // create inbox
+
+  const inboxRes = await client.inboxes.create({
+    username: `x402-${Date.now()}`,
+  });
+  console.log("Created inbox: ", inboxRes.inboxId);
+
+
+  // subscribe to inbox
+
+  const socket = await client.websockets.connect();
+  console.log("Connected to websocket");
+
+  socket.on("message", async (event) => {
+    if (event.type === "subscribed") {
+      console.log("Subscribed to", event.inboxIds);
+    } else if (event.type === "event" && event.eventType === "message.received") {
+      console.log("Received message from: ", event.message.from);
+    }
+  });
+
+  socket.sendSubscribe({
+    type: "subscribe",
+    inboxIds: [inboxRes.inboxId],
+  });
+  ```
+
+  ```typescript title="Solana"
+  import { createKeyPairSignerFromBytes } from "@solana/kit";
+  import { base58 } from "@scure/base";
+  import { x402Client } from "@x402/fetch";
+  import { ExactSvmClient, toClientSvmSigner } from "@x402/svm";
+
+  import { AgentMailClient } from "agentmail";
+
+
+  // setup x402 client
+
+  const PRIVATE_KEY = "base58-encoded-private-key...";
+
+  const keypair = await createKeyPairSignerFromBytes(
+    base58.decode(PRIVATE_KEY)
+  );
+
+  const x402 = new x402Client();
+  x402.register("solana:*", new ExactSvmClient(toClientSvmSigner(keypair)));
+
+
+  // setup AgentMail client
+
+  export const client = new AgentMailClient({ x402 });
+
+
+  // create inbox
+
+  const inboxRes = await client.inboxes.create({
+    username: `x402-${Date.now()}`,
+  });
+  console.log("Created inbox: ", inboxRes.inboxId);
+
+
+  // subscribe to inbox
+
+  const socket = await client.websockets.connect();
+  console.log("Connected to websocket");
+
+  socket.on("message", async (event) => {
+    if (event.type === "subscribed") {
+      console.log("Subscribed to", event.inboxIds);
+    } else if (event.type === "event" && event.eventType === "message.received") {
+      console.log("Received message from: ", event.message.from);
+    }
+  });
+
+  socket.sendSubscribe({
+    type: "subscribe",
+    inboxIds: [inboxRes.inboxId],
+  });
+  ```
+</CodeBlocks>
+
+## How it works
+
+When you pass an `x402` client to `AgentMailClient`, the SDK automatically handles payment negotiation for each API request. If the server responds with a `402 Payment Required` status, the x402 client signs a payment using your wallet and retries the request with the payment attached.
+
+This means your agent can use the full AgentMail API (inboxes, messages, threads, attachments) without needing a traditional API key. Payment happens per-request over HTTP.
+
+## Resources
+
+* [x402 documentation](https://www.x402.org/)
+* [AgentMail API reference](/api-reference)
+* [WebSockets overview](/websockets)
+
+
 ***
 
 title: 'Guide: Sending & Receiving Email'
@@ -2289,6 +2687,11 @@ Here's the step-by-step logic for a polling-based conversational agent.
       const messageIdToReplyTo = lastMessage.message_id;
       ```
     </CodeBlocks>
+
+    <Tip>
+      Use `last_message.extracted_text` (or `extracted_html`) when you need
+      just the new reply content, without quoted history.
+    </Tip>
   </Step>
 
   <Step title="3. Send the Reply and Update Labels">
@@ -3218,6 +3621,23 @@ This event-driven approach is more efficient and allows you to build fast, respo
 * **Real-Time Speed:** Build conversational agents that can reply to incoming emails in seconds.
 * **Efficiency:** Eliminates the need for constant polling, which saves you computational resources and simplifies your application logic.
 
+## Available Events
+
+AgentMail supports seven webhook event types. When creating a webhook, you can subscribe to specific events or receive all of them. See [Webhook Events](/events) for full payload details.
+
+**Message events:**
+
+* **`message.received`** — New email received and processed in one of your inboxes
+* **`message.sent`** — Message successfully sent from your inbox
+* **`message.delivered`** — Delivery confirmed by the recipient's mail server
+* **`message.bounced`** — Message failed to deliver and bounced back
+* **`message.complained`** — Recipient marked your message as spam
+* **`message.rejected`** — Message rejected before send (validation or policy)
+
+**Domain events:**
+
+* **`domain.verified`** — Custom domain successfully verified
+
 ## The Webhook Workflow
 
 The process is straightforward:
@@ -3233,26 +3653,30 @@ The process is straightforward:
     <CodeBlocks>
       ```python
       client.webhooks.create(
-          url="https://<your-ngrok-url>.ngrok-free.app/webhooks"
+          url="https://<your-ngrok-url>.ngrok-free.app/webhooks",
+          events=["message.received", "message.sent"],
       )
       ```
 
       ```typescript
       await client.webhooks.create({
           url: "https://<your-ngrok-url>.ngrok-free.app/webhooks",
+          events: ["message.received", "message.sent"],
       });
       ```
     </CodeBlocks>
+
+    Specify which events to receive; omit `events` to subscribe to all event types.
   </Step>
 
   <Step title="3. AgentMail Sends Events">
-    When a new message is received in one of your inboxes, AgentMail will immediately send a `POST` request with a JSON payload to your registered URL.
+    When an event occurs (e.g. a new message is received, a message is delivered, or a domain is verified), AgentMail sends a `POST` request with a JSON payload to your registered URL.
   </Step>
 </Steps>
 
 ## Payload Structure
 
-When AgentMail sends a webhook, the payload will have the following structure.
+When AgentMail sends a webhook, the payload includes `event_type` and `event_id`, plus event-specific data. The example below shows a `message.received` payload; other events use different top-level objects (`send`, `delivery`, `bounce`, etc.). See [Webhook Events](/events) for each event's payload shape.
 
 ```json Webhook Payload
 {
@@ -3294,7 +3718,7 @@ When AgentMail sends a webhook, the payload will have the following structure.
 
 ### Field Descriptions
 
-* **`event_type`** (`string`): The name of the event. Currently, this will always be `message.received`.
+* **`event_type`** (`string`): The event type (e.g. `message.received`, `message.sent`, `message.delivered`). Payload structure varies by event—see [Webhook Events](/events) for each event's shape.
 * **`event_id`** (`string`): A unique identifier for this specific event delivery.
 * **`message`** (`object`): A dictionary containing the full details of the received email message.
   * **`from_`** (`array<string>`): The sender's email address. Note the trailing underscore to avoid conflict with the Python keyword.
@@ -3349,6 +3773,84 @@ All webhook payloads follow the same basic structure:
 }
 ```
 
+## Parsing events with SDKs
+
+The AgentMail SDKs export typed classes for each webhook event, so you can parse raw payloads into fully typed objects.
+
+<CodeBlocks>
+  ```typescript title="TypeScript"
+  import { serialization } from "agentmail";
+
+  async function handleWebhook(payload: Record<string, unknown>) {
+    const eventType = payload.event_type;
+
+    if (eventType === "message.received") {
+      const event = await serialization.events.MessageReceivedEvent.parse(payload);
+      // access typed fields
+      console.log(event.message.subject);
+      console.log(event.thread.messageCount);
+    } else if (eventType === "message.sent") {
+      const event = await serialization.events.MessageSentEvent.parse(payload);
+      console.log(event.send.recipients);
+    } else if (eventType === "message.bounced") {
+      const event = await serialization.events.MessageBouncedEvent.parse(payload);
+      console.log(event.bounce.type);
+    } else if (eventType === "message.delivered") {
+      const event = await serialization.events.MessageDeliveredEvent.parse(payload);
+      console.log(event.delivery.recipients);
+    } else if (eventType === "message.complained") {
+      const event = await serialization.events.MessageComplainedEvent.parse(payload);
+      console.log(event.complaint.type);
+    } else if (eventType === "message.rejected") {
+      const event = await serialization.events.MessageRejectedEvent.parse(payload);
+      console.log(event.reject.reason);
+    } else if (eventType === "domain.verified") {
+      const event = await serialization.events.DomainVerifiedEvent.parse(payload);
+      console.log(event.domain.status);
+    }
+  }
+  ```
+
+  ```python title="Python"
+  from agentmail import (
+      MessageReceivedEvent,
+      MessageSentEvent,
+      MessageBouncedEvent,
+      MessageDeliveredEvent,
+      MessageComplainedEvent,
+      MessageRejectedEvent,
+      DomainVerifiedEvent,
+  )
+
+  def handle_webhook(payload: dict):
+      event_type = payload.get("event_type")
+
+      if event_type == "message.received":
+          event = MessageReceivedEvent(**payload)
+          # access typed fields
+          print(event.message.subject)
+          print(event.thread.message_count)
+      elif event_type == "message.sent":
+          event = MessageSentEvent(**payload)
+          print(event.send.recipients)
+      elif event_type == "message.bounced":
+          event = MessageBouncedEvent(**payload)
+          print(event.bounce.type)
+      elif event_type == "message.delivered":
+          event = MessageDeliveredEvent(**payload)
+          print(event.delivery.recipients)
+      elif event_type == "message.complained":
+          event = MessageComplainedEvent(**payload)
+          print(event.complaint.type)
+      elif event_type == "message.rejected":
+          event = MessageRejectedEvent(**payload)
+          print(event.reject.reason)
+      elif event_type == "domain.verified":
+          event = DomainVerifiedEvent(**payload)
+          print(event.domain.status)
+  ```
+</CodeBlocks>
+
 ## Message Events
 
 ### `message.received`
@@ -3375,26 +3877,30 @@ All webhook payloads follow the same basic structure:
       "message_id": "msg_123abc",
       "labels": ["received"],
       "timestamp": "2023-10-27T10:00:00Z",
-      "from": [
-        {
-          "name": "Jane Doe",
-          "email": "jane@example.com"
-        }
-      ],
-      "to": [
-        {
-          "name": "Support Agent",
-          "email": "support@agentmail.to"
-        }
-      ],
+      "from": "Jane Doe <jane@example.com>",
+      "to": ["Support Agent <support@agentmail.to>"],
       "subject": "Question about my account",
       "preview": "A short preview of the email text...",
       "text": "The full text body of the email.",
       "html": "<html>...</html>",
+      "size": 2048,
+      "updated_at": "2023-10-27T10:00:00Z",
       "created_at": "2023-10-27T10:00:00Z"
     },
     "thread": {
-      // ... thread properties
+      "inbox_id": "inbox_456def",
+      "thread_id": "thd_789ghi",
+      "labels": ["received"],
+      "timestamp": "2023-10-27T10:00:00Z",
+      "senders": ["Jane Doe <jane@example.com>"],
+      "recipients": ["Support Agent <support@agentmail.to>"],
+      "subject": "Question about my account",
+      "preview": "A short preview of the email text...",
+      "last_message_id": "msg_123abc",
+      "message_count": 1,
+      "size": 2048,
+      "updated_at": "2023-10-27T10:00:00Z",
+      "created_at": "2023-10-27T10:00:00Z"
     }
   }
   ```
@@ -3699,6 +4205,7 @@ webhook_url = "https://your-subdomain.ngrok-free.app/webhooks"
 
 webhook = client.webhooks.create(
     url=webhook_url,
+    events=["message.received"],  # add others (e.g. message.sent) as needed
     client_id="webhook-demo-webhook"  # Ensures idempotency
 )
 
@@ -3941,7 +4448,13 @@ The easiest way to verify webhooks is using the official Svix library, which han
       except WebhookVerificationError as e:
           return ('', 400)
 
-      # Do something with the message...
+      # handle by event type (msg is the verified payload)
+      if msg.get("event_type") == "message.received":
+          # process incoming email...
+          pass
+      elif msg.get("event_type") == "domain.verified":
+          # enable domain features...
+          pass
 
       return ('', 204)
 
@@ -3975,8 +4488,12 @@ The easiest way to verify webhooks is using the official Svix library, which han
         const wh = new Webhook(secret);
         const msg = wh.verify(payload, headers);
 
-        // Do something with the message...
-        console.log("Webhook verified:", msg);
+        // handle by event type (msg is the verified payload)
+        if (msg.event_type === "message.received") {
+          // process incoming email...
+        } else if (msg.event_type === "domain.verified") {
+          // enable domain features...
+        }
 
         res.status(204).send();
       } catch (err) {
@@ -4031,7 +4548,13 @@ Create a webhook server file:
           print(f"Verification failed: {e}")
           return ('', 400)
 
-      # Do something with the message...
+      # handle by event type (msg is the verified payload)
+      if msg.get("event_type") == "message.received":
+          # process incoming email...
+          pass
+      elif msg.get("event_type") == "domain.verified":
+          # enable domain features...
+          pass
 
       return ('', 204)
 
@@ -4064,8 +4587,12 @@ Create a webhook server file:
         const wh = new Webhook(secret);
         const msg = wh.verify(payload, headers);
 
-        // Do something with the message...
-        console.log("Webhook verified:", msg);
+        // handle by event type (msg is the verified payload)
+        if (msg.event_type === "message.received") {
+          // process incoming email...
+        } else if (msg.event_type === "domain.verified") {
+          // enable domain features...
+        }
 
         res.status(204).send();
       } catch (err) {
@@ -7634,6 +8161,11 @@ practices and security.
     [Webhooks Overview](/overview).
   </Accordion>
 
+  <Accordion title="How do I get just the new content from a reply?">
+    Use `extracted_text` or `extracted_html` on the Message object. AgentMail
+    strips quoted text automatically, so you get only the new reply content.
+  </Accordion>
+
   <Accordion title="How do I make sure I don't end up in spam?">
     Email deliverability is a complex topic. We go in depth in our [Email
     Deliverability best practices guide](/email-deliverability).
@@ -8219,8 +8751,7 @@ and get support.
 </Callout>
 
 
-***
-
+ ---
 title: Support
 slug: support
 description: Get help with AgentMail through our support channels.
@@ -21862,37 +22393,34 @@ components:
 
 ## SDK Code Examples
 
-```python
-import requests
-
-url = "https://api.agentmail.to/v0/lists/send/allow"
+```typescript
+import { AgentMailClient } from "agentmail";
 
-payload = { "entry": "entry" }
-headers = {
-    "Authorization": "Bearer <api_key>",
-    "Content-Type": "application/json"
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.lists.create("send", "allow", {
+        entry: "entry",
+    });
 }
+main();
 
-response = requests.post(url, json=payload, headers=headers)
-
-print(response.json())
 ```
 
-```javascript
-const url = 'https://api.agentmail.to/v0/lists/send/allow';
-const options = {
-  method: 'POST',
-  headers: {Authorization: 'Bearer <api_key>', 'Content-Type': 'application/json'},
-  body: '{"entry":"entry"}'
-};
+```python
+from agentmail import AgentMail
+
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE"
+)
+
+client.lists.create(
+    direction="send",
+    type="allow",
+    entry="entry"
+)
 
-try {
-  const response = await fetch(url, options);
-  const data = await response.json();
-  console.log(data);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ```go
@@ -22171,29 +22699,31 @@ components:
 
 ## SDK Code Examples
 
-```python
-import requests
+```typescript
+import { AgentMailClient } from "agentmail";
 
-url = "https://api.agentmail.to/v0/lists/send/allow"
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.lists.list("send", "allow", {});
+}
+main();
 
-headers = {"Authorization": "Bearer <api_key>"}
+```
 
-response = requests.get(url, headers=headers)
+```python
+from agentmail import AgentMail
 
-print(response.json())
-```
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE"
+)
 
-```javascript
-const url = 'https://api.agentmail.to/v0/lists/send/allow';
-const options = {method: 'GET', headers: {Authorization: 'Bearer <api_key>'}};
+client.lists.list(
+    direction="send",
+    type="allow"
+)
 
-try {
-  const response = await fetch(url, options);
-  const data = await response.json();
-  console.log(data);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ```go
@@ -22442,29 +22972,32 @@ components:
 
 ## SDK Code Examples
 
-```python
-import requests
+```typescript
+import { AgentMailClient } from "agentmail";
 
-url = "https://api.agentmail.to/v0/lists/send/allow/entry"
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.lists.get("send", "allow", "entry");
+}
+main();
 
-headers = {"Authorization": "Bearer <api_key>"}
+```
 
-response = requests.get(url, headers=headers)
+```python
+from agentmail import AgentMail
 
-print(response.json())
-```
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE"
+)
 
-```javascript
-const url = 'https://api.agentmail.to/v0/lists/send/allow/entry';
-const options = {method: 'GET', headers: {Authorization: 'Bearer <api_key>'}};
+client.lists.get(
+    direction="send",
+    type="allow",
+    entry="entry"
+)
 
-try {
-  const response = await fetch(url, options);
-  const data = await response.json();
-  console.log(data);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ```go
@@ -22669,29 +23202,32 @@ components:
 
 ## SDK Code Examples
 
-```python
-import requests
+```typescript
+import { AgentMailClient } from "agentmail";
 
-url = "https://api.agentmail.to/v0/lists/send/allow/entry"
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.lists.delete("send", "allow", "entry");
+}
+main();
 
-headers = {"Authorization": "Bearer <api_key>"}
+```
 
-response = requests.delete(url, headers=headers)
+```python
+from agentmail import AgentMail
 
-print(response.json())
-```
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE"
+)
 
-```javascript
-const url = 'https://api.agentmail.to/v0/lists/send/allow/entry';
-const options = {method: 'DELETE', headers: {Authorization: 'Bearer <api_key>'}};
+client.lists.delete(
+    direction="send",
+    type="allow",
+    entry="entry"
+)
 
-try {
-  const response = await fetch(url, options);
-  const data = await response.json();
-  console.log(data);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ```go
@@ -33005,37 +33541,35 @@ components:
 
 ## SDK Code Examples
 
-```python
-import requests
-
-url = "https://api.agentmail.to/v0/pods/pod_id/lists/send/allow"
+```typescript
+import { AgentMailClient } from "agentmail";
 
-payload = { "entry": "entry" }
-headers = {
-    "Authorization": "Bearer <api_key>",
-    "Content-Type": "application/json"
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.pods.lists.create("pod_id", "send", "allow", {
+        entry: "entry",
+    });
 }
+main();
 
-response = requests.post(url, json=payload, headers=headers)
-
-print(response.json())
 ```
 
-```javascript
-const url = 'https://api.agentmail.to/v0/pods/pod_id/lists/send/allow';
-const options = {
-  method: 'POST',
-  headers: {Authorization: 'Bearer <api_key>', 'Content-Type': 'application/json'},
-  body: '{"entry":"entry"}'
-};
+```python
+from agentmail import AgentMail
+
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE"
+)
+
+client.pods.lists.create(
+    pod_id="pod_id",
+    direction="send",
+    type="allow",
+    entry="entry"
+)
 
-try {
-  const response = await fetch(url, options);
-  const data = await response.json();
-  console.log(data);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ```go
@@ -33330,29 +33864,32 @@ components:
 
 ## SDK Code Examples
 
-```python
-import requests
+```typescript
+import { AgentMailClient } from "agentmail";
 
-url = "https://api.agentmail.to/v0/pods/pod_id/lists/send/allow"
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.pods.lists.list("pod_id", "send", "allow", {});
+}
+main();
 
-headers = {"Authorization": "Bearer <api_key>"}
+```
 
-response = requests.get(url, headers=headers)
+```python
+from agentmail import AgentMail
 
-print(response.json())
-```
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE"
+)
 
-```javascript
-const url = 'https://api.agentmail.to/v0/pods/pod_id/lists/send/allow';
-const options = {method: 'GET', headers: {Authorization: 'Bearer <api_key>'}};
+client.pods.lists.list(
+    pod_id="pod_id",
+    direction="send",
+    type="allow"
+)
 
-try {
-  const response = await fetch(url, options);
-  const data = await response.json();
-  console.log(data);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ```go
@@ -33617,29 +34154,33 @@ components:
 
 ## SDK Code Examples
 
-```python
-import requests
+```typescript
+import { AgentMailClient } from "agentmail";
 
-url = "https://api.agentmail.to/v0/pods/pod_id/lists/send/allow/entry"
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.pods.lists.get("pod_id", "send", "allow", "entry");
+}
+main();
 
-headers = {"Authorization": "Bearer <api_key>"}
+```
 
-response = requests.get(url, headers=headers)
+```python
+from agentmail import AgentMail
 
-print(response.json())
-```
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE"
+)
 
-```javascript
-const url = 'https://api.agentmail.to/v0/pods/pod_id/lists/send/allow/entry';
-const options = {method: 'GET', headers: {Authorization: 'Bearer <api_key>'}};
+client.pods.lists.get(
+    pod_id="pod_id",
+    direction="send",
+    type="allow",
+    entry="entry"
+)
 
-try {
-  const response = await fetch(url, options);
-  const data = await response.json();
-  console.log(data);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ```go
@@ -33853,29 +34394,33 @@ components:
 
 ## SDK Code Examples
 
-```python
-import requests
+```typescript
+import { AgentMailClient } from "agentmail";
 
-url = "https://api.agentmail.to/v0/pods/pod_id/lists/send/allow/entry"
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.pods.lists.delete("pod_id", "send", "allow", "entry");
+}
+main();
 
-headers = {"Authorization": "Bearer <api_key>"}
+```
 
-response = requests.delete(url, headers=headers)
+```python
+from agentmail import AgentMail
 
-print(response.json())
-```
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE"
+)
 
-```javascript
-const url = 'https://api.agentmail.to/v0/pods/pod_id/lists/send/allow/entry';
-const options = {method: 'DELETE', headers: {Authorization: 'Bearer <api_key>'}};
+client.pods.lists.delete(
+    pod_id="pod_id",
+    direction="send",
+    type="allow",
+    entry="entry"
+)
 
-try {
-  const response = await fetch(url, options);
-  const data = await response.json();
-  console.log(data);
-} catch (error) {
-  console.error(error);
-}
 ```
 
 ```go