agentmail 0.4.18 → 0.4.20

package/dist/llms-full.txt

@@ -1,9 +1,10 @@
-***
+> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.agentmail.to/llms.txt. For full content including API reference and SDK examples, see https://docs.agentmail.to/llms-full.txt.
+
+# AgentMail | Documentation
+
+# Welcome
 
-title: Welcome
-slug: welcome
-description: Your starting point for building with the AgentMail API.
----------------------------------------------------------------------
+> Your starting point for building with the AgentMail API.
 
 <Tip title="Welcome to AgentMail!" icon="fa-solid fa-star">
   We're thrilled to have you here! Dive in to learn how to give your AI agents their own email inboxes.
@@ -43,13 +44,7 @@ AgentMail is an API platform for giving AI agents their own inboxes to send, rec
   </Card>
 </CardGroup>
 
-
-***
-
-title: Introduction
-subtitle: Give AI agents email inboxes
-slug: introduction
-------------------
+# Introduction
 
 ## What is AgentMail?
 
@@ -147,7 +142,13 @@ Our customers use AgentMail for agent identity, authentication, and communicatio
 ## Get Started
 
 <CardGroup>
-  <Card title="Quickstart" icon="fa-solid fa-book" href="/quickstart" />
+  <Card title="Quickstart" icon="fa-solid fa-book" href="/quickstart">
+    Create your first inbox and send an email in minutes.
+  </Card>
+
+  <Card title="Receive emails" icon="fa-solid fa-bell" href="/webhooks-overview">
+    Set up webhooks or WebSockets to receive incoming messages in real time.
+  </Card>
 
   <Card title="API Reference" icon="fa-solid fa-code" href="/api-reference" />
 </CardGroup>
@@ -160,192 +161,118 @@ Our customers use AgentMail for agent identity, authentication, and communicatio
   <Card title="Email" icon="fa-solid fa-envelope" href="mailto:support@agentmail.cc" />
 </CardGroup>
 
+# Quickstart
 
-***
-
-title: Quickstart
-subtitle: Create your first inbox with the AgentMail API
-slug: quickstart
-description: >-
-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
-  ```
-
-  ```bash title="CLI"
-  npm install -g agentmail-cli
-  ```
-</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!" });
-  })();
-  ```
-
-  ```bash title="CLI"
-  # create an inbox
-  agentmail inboxes create
+> Follow this guide to make your first AgentMail API request and create a new email inbox.
 
-  # send an email (replace <inbox_id> with the id from above)
-  agentmail inboxes:messages send \
-    --inbox-id <inbox_id> \
-    --to user@example.com \
-    --subject "Hello" \
-    --text "Hello from my agent!"
-  ```
-</CodeBlocks>
+## For Agents
 
-## Copy for Cursor / Claude
+For agents that sign themselves up programmatically, no Console or dashboard needed. The agent registers itself using an email you provide and receives an API key in response. This flow is for first-time users only: human email addresses already signed up with AgentMail will not work here.
 
-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.
+<Steps>
+  <Step title="Sign up">
+    The agent registers itself using the human email you provide and gets back an API key, inbox ID, and organization ID. An OTP is sent to that email.
 
-<CodeBlocks>
-  ```python title="Python"
-  """
-  AgentMail Python Quickstart — copy into Cursor/Claude for instant setup.
+    <CodeBlocks>
+      ```bash title="CLI"
+      npm install -g agentmail-cli
 
-  Setup: pip install agentmail python-dotenv. Set AGENTMAIL_API_KEY in .env.
+      agentmail agent sign-up \
+        --human-email you@example.com \
+        --username my-agent
+      ```
 
-  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
+      ```bash title="cURL"
+      curl -X POST https://api.agentmail.to/agent/sign-up \
+        -H "Content-Type: application/json" \
+        -d '{
+          "human_email": "you@example.com",
+          "username": "my-agent"
+        }'
+      # returns { api_key, inbox_id, organization_id }
+      ```
+    </CodeBlocks>
 
-  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
+    <Info>
+      The sign-up endpoint is idempotent. Calling it again with the same email rotates the API key and resends the OTP if expired.
+    </Info>
+  </Step>
 
-  load_dotenv()
-  client = AgentMail(api_key=os.getenv("AGENTMAIL_API_KEY"))
+  <Step title="Verify with the OTP">
+    Check the human's email for a 6-digit OTP code and verify to unlock full permissions.
 
-  # Create inbox (client_id enables safe retries)
-  inbox = client.inboxes.create(client_id="my-agent-inbox-v1")
+    <CodeBlocks>
+      ```bash title="CLI"
+      export AGENTMAIL_API_KEY="am_..."  # from the sign-up response
 
-  # 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
+      agentmail agent verify --otp-code 123456
+      ```
 
-  # Receive messages
-  for msg in client.inboxes.messages.list(inbox.inbox_id, limit=10).messages:
-      print(msg.subject, msg.extracted_text or msg.text)
-  ```
+      ```bash title="cURL"
+      curl -X POST https://api.agentmail.to/agent/verify \
+        -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
+        -H "Content-Type: application/json" \
+        -d '{ "otp_code": "123456" }'
+      ```
+    </CodeBlocks>
+  </Step>
 
-  ```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";
+  <Step title="Create an inbox and send an email">
+    With the API key from sign-up, the agent can create inboxes and send mail on its own.
 
-  const client = new AgentMailClient({
-    apiKey: process.env.AGENTMAIL_API_KEY!,
-  });
+    <CodeBlocks>
+      ```bash title="CLI"
+      # create an inbox
+      agentmail inboxes create
 
-  async function main() {
-    // Create inbox (clientId enables safe retries)
-    const inbox = await client.inboxes.create({
-      clientId: "my-agent-inbox-v1",
-    });
+      # send an email (replace <inbox_id> with the id from above)
+      agentmail inboxes:messages send \
+        --inbox-id <inbox_id> \
+        --to recipient@example.com \
+        --subject "Hello" \
+        --text "Hello from my agent!"
+      ```
 
-    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}`);
-    }
+      ```bash title="cURL"
+      # create an inbox (client_id enables safe retries)
+      curl -X POST https://api.agentmail.to/inboxes \
+        -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
+        -H "Content-Type: application/json" \
+        -d '{ "client_id": "my-agent-inbox-v1" }'
+      # returns { inbox_id, ... }
 
-    // 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>
+      # send an email (replace <inbox_id> with the id from above)
+      curl -X POST https://api.agentmail.to/inboxes/<inbox_id>/messages/send \
+        -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
+        -H "Content-Type: application/json" \
+        -d '{
+          "to": "recipient@example.com",
+          "subject": "Hello from AgentMail",
+          "text": "Plain text body"
+        }'
+      ```
+    </CodeBlocks>
+  </Step>
+</Steps>
 
-<Tip>
-  When receiving emails, messages include `extracted_text` and `extracted_html`
-  for reply content without quoted history.
-</Tip>
+## For Humans
 
-This guide will walk you through installing the AgentMail SDK, authenticating with your API key, and creating your first email inbox.
+For developers who want to try AgentMail from the Console.
 
 <Steps>
-  <Step title="Access the AgentMail Console">
-    First, you'll need to access the AgentMail Console to manage your account and API keys. Click the link below to get started.
+  <Step title="Sign up and get an API key">
+    Go to the [AgentMail Console](https://console.agentmail.to), create an account, and generate an API key from the dashboard.
+    ![API Key Creation Screenshot](https://files.buildwithfern.com/https://agentmail-production.docs.buildwithfern.com/4e665f546efdf08d30178fcfbd996298ed7b3d1d44709fc742ed5315fed9532e/assets/api-key-creation.png)
+  </Step>
 
-    <Card title="Open AgentMail Console" icon="fa-solid fa-desktop" href="https://console.agentmail.to" target="_blank" />
+  <Step title="Store your API key">
+    Create a `.env` file in your project root and add your key:
 
-    If you don't have an account yet, you can sign up directly from the console. Once you're logged in, you'll be able to manage your inboxes, view analytics, and create API keys.
-  </Step>
+    ```bash
+    AGENTMAIL_API_KEY=am_...
+    ```
 
-  <Step title="Create an API Key">
-    Now that you're in the console, you'll need to create an API key to
-    authenticate your requests. Navigate to the API Keys section in your console
-    dashboard. ![API Key Creation Screenshot](https://files.buildwithfern.com/https://agentmail-production.docs.buildwithfern.com/4e665f546efdf08d30178fcfbd996298ed7b3d1d44709fc742ed5315fed9532e/assets/api-key-creation.png) Click
-    "Create New API Key" and give it a descriptive name. Once created, copy the
-    API key and store it securely. Create a `.env` file in your project's root
-    directory and add your key to it. We recommend using environment variables to
-    keep your keys secure.
+    We recommend using environment variables to keep your keys secure.
   </Step>
 
   <Step title="Install the SDK">
@@ -368,10 +295,9 @@ This guide will walk you through installing the AgentMail SDK, authenticating wi
   </Step>
 
   <Step title="Create an inbox and send an email">
-    Now you're ready to make your first API call. Create a new file (e.g.,
-    `quickstart.py` or `quickstart.ts`) and add the following code. This script
-    will initialize the AgentMail client, create a new inbox, and then send a
-    test email.
+    Create a new file (e.g., `quickstart.py` or `quickstart.ts`) and add the
+    following code. This script initializes the AgentMail client, creates a new
+    inbox, and sends a test email.
 
     <CodeBlocks>
       ```python title="Python"
@@ -379,28 +305,26 @@ This guide will walk you through installing the AgentMail SDK, authenticating wi
       from dotenv import load_dotenv
       from agentmail import AgentMail
 
-      # Load the API key from the .env file
+      # load the API key from the .env file
       load_dotenv()
       api_key = os.getenv("AGENTMAIL_API_KEY")
 
-      # Initialize the client
+      # initialize the client
       client = AgentMail(api_key=api_key)
 
-      # Create an inbox
+      # create an inbox
       print("Creating inbox...")
       inbox = client.inboxes.create() # domain is optional
       print("Inbox created successfully!")
       print(inbox)
 
-      # Send Email
-
+      # send an email from the new inbox
       client.inboxes.messages.send(
         inbox.inbox_id,
         to="your-email@example.com",
         subject="Hello from AgentMail!",
         text="This is my first email sent with the AgentMail API.",
       )
-
       ```
 
       ```typescript title="TypeScript"
@@ -408,18 +332,18 @@ This guide will walk you through installing the AgentMail SDK, authenticating wi
       import "dotenv/config"; // loads .env file
 
       async function main() {
-        // Initialize the client
+        // initialize the client
         const client = new AgentMailClient({
           apiKey: process.env.AGENTMAIL_API_KEY,
         });
 
-        // Create an inbox
+        // create an inbox
         console.log("Creating inbox...");
         const inbox = await client.inboxes.create(); // domain is optional
         console.log("Inbox created successfully!");
         console.log(inbox);
 
-        // Send an email from the new inbox
+        // send an email from the new inbox
         console.log("Sending email...");
         await client.inboxes.messages.send(inbox.inboxId, {
           to: "your-email@example.com",
@@ -473,25 +397,150 @@ This guide will walk you through installing the AgentMail SDK, authenticating wi
   </Step>
 </Steps>
 
+## 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.
+
+  Agent sign-up (no API key needed):
+  - agent.sign_up(human_email, username) — returns api_key, inbox_id, organization_id
+  - agent.verify(otp_code) — verify with OTP sent to human_email
+
+  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.
+   *
+   * Agent sign-up (no API key needed):
+   * - agent.signUp({ humanEmail, username }) — returns apiKey, inboxId, organizationId
+   * - agent.verify({ otpCode }) — verify with OTP sent to humanEmail
+   *
+   * 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>
+
 ## Next Steps
 
-Congrats, you sent your first email via AgentMail. But this isn't our strength. Explore the full power of creating agents that can autonomously reply, take action, parse attachments, semantically search your inbox, by exploring our docs and tutorials below.
+You've created an inbox and sent your first email. Now set up your agent to receive and respond to incoming messages:
+
+<CardGroup>
+  <Card title="Receive emails with WebSockets" icon="fa-solid fa-plug" href="/websockets">
+    The fastest way to receive emails. No public URL or ngrok needed.
+  </Card>
+
+  <Card title="Receive emails with webhooks" icon="fa-solid fa-bell" href="/webhooks-overview">
+    Get real-time HTTP notifications when emails arrive.
+  </Card>
+
+  <Card title="Sending & receiving guide" icon="fa-solid fa-right-left" href="/sending-receiving-email">
+    Build a complete conversational agent workflow.
+  </Card>
+
+  <Card title="API Reference" icon="fa-solid fa-code" href="/api-reference">
+    Explore the full API with interactive examples.
+  </Card>
+</CardGroup>
 
 <Note>
   Looking for a different language? Email us at
   [support@agentmail.cc](mailto:support@agentmail.cc) and we'll get you set up.
 </Note>
 
+# Inboxes
 
-***
-
-title: Inboxes
-subtitle: The foundation of your agent's identity and communication.
-slug: inboxes
-description: >-
-Learn how AgentMail Inboxes act as scalable, API-first email accounts for your
-agents.
--------
+> Learn how AgentMail Inboxes act as scalable, API-first email accounts for your agents.
 
 ## What is an Inbox?
 
@@ -612,8 +661,8 @@ Here at AgentMail we've now made an `Inbox` an API resource, meaning you can per
     --domain domain.com \
     --display-name "Docs Tester"
 
-  # retrieve an inbox
-  agentmail inboxes retrieve --inbox-id my_name@domain.com
+  # get an inbox
+  agentmail inboxes get --inbox-id my_name@domain.com
 
   # list all inboxes
   agentmail inboxes list
@@ -727,16 +776,9 @@ Copy one of the blocks below into Cursor or Claude for complete Inboxes API know
   ```
 </CodeBlocks>
 
+# Messages
 
-***
-
-title: Messages
-subtitle: The fundamental unit of communication for your agents.
-slug: messages
-description: >-
-Learn how to send, receive, and manage emails as Message objects with the
-AgentMail API.
---------------
+> Learn how to send, receive, and manage emails as Message objects with the AgentMail API.
 
 ## What is a Message?
 
@@ -938,8 +980,8 @@ You can retrieve the details of any specific `Message` by providing its ID along
   ```
 
   ```bash title="CLI"
-  # retrieve a specific message
-  agentmail inboxes:messages retrieve \
+  # get a specific message
+  agentmail inboxes:messages get \
     --inbox-id my_inbox@agentmail.to \
     --message-id "<abc123@agentmail.to>"
   ```
@@ -1199,10 +1241,14 @@ When processing incoming messages, always treat `html` as the primary content so
 
 ## Receiving `Messages`
 
+<Warning>
+  **Inbound emails require the sender's domain to have SPF or DKIM configured.** To reduce spoofing and phishing, AgentMail drops inbound emails when the sender's domain has neither SPF nor DKIM set up. If a sender reports that their email never arrived, this is the most likely cause. Once they configure SPF/DKIM on their domain, their emails will start landing in your inbox again. See [Why are my emails not showing up?](/knowledge-base/inbound-emails-missing) for details.
+</Warning>
+
 While you can periodically list `Messages` to check for new emails, the most efficient way to handle incoming `Messages` for your agents is with `Webhooks`. By configuring a `Webhook` endpoint, AgentMail can notify your application/agent in real-time as soon as a new `Message` arrives, so you can take action on them.
 
 <CardGroup>
-  <Card title="Guide: Webhooks" icon="fa-solid fa-bolt" href="/overview">
+  <Card title="Guide: Webhooks" icon="fa-solid fa-bolt" href="/webhooks-overview">
     Learn how to set up webhooks for real-time message processing.
   </Card>
 </CardGroup>
@@ -1268,16 +1314,9 @@ AgentMail doesn't have a dedicated "mark as read" endpoint — instead, you use
 ```
 ```
 
+# Threads
 
-***
-
-title: Threads
-subtitle: Organizing conversations across your Inboxes.
-slug: threads
-description: >-
-Learn how AgentMail Threads group messages into conversations and how to query
-them across your entire organization.
--------------------------------------
+> Learn how AgentMail Threads group messages into conversations and how to query them across your entire organization.
 
 ## What is a Thread?
 
@@ -1298,7 +1337,7 @@ This is the standard way to retrieve all the conversations associated with a sin
   # You'll need an inbox ID to list threads from.
   inbox_id = "inbound-agent@agentmail.to"
 
-  # This retrieves all threads within the specified Inbox
+  # This loads all threads within the specified Inbox
 
   inbox_threads = client.inboxes.threads.list(inbox_id=inbox_id)
 
@@ -1308,7 +1347,7 @@ This is the standard way to retrieve all the conversations associated with a sin
   // You'll need an inbox ID to list threads from.
   const inboxId = "inbound-agent@agentmail.to";
 
-  // This retrieves all threads within the specified Inbox
+  // This loads all threads within the specified Inbox
   const inboxThreads = await client.inboxes.threads.list("inbound-agent@agentmail.to");
 
   console.log(`Found ${inboxThreads.count} threads in Inbox ${inboxId}.`);
@@ -1365,7 +1404,7 @@ You can also retrieve a single `Thread` by its ID. This will return the `Thread`
   ```python
   thread_id = "thread_456def"
 
-  # This retrieves a single thread and its messages
+  # This loads a single thread and its messages
 
   thread = client.threads.get(
   thread_id="thread_id"
@@ -1378,7 +1417,7 @@ You can also retrieve a single `Thread` by its ID. This will return the `Thread`
   ```typescript title="TypeScript"
   const threadId = "thread_456def";
 
-  // This retrieves a single thread and its messages
+  // This loads a single thread and its messages
   const thread = await client.threads.get(
   	"thread_id"
   )
@@ -1387,8 +1426,8 @@ You can also retrieve a single `Thread` by its ID. This will return the `Thread`
   ```
 
   ```bash title="CLI"
-  # retrieve a single thread by id
-  agentmail threads retrieve \
+  # get a single thread by id
+  agentmail threads get \
     --thread-id thread_456def
   ```
 </CodeBlocks>
@@ -1476,16 +1515,9 @@ Copy one of the blocks below into Cursor or Claude for complete Threads API know
   ```
 </CodeBlocks>
 
+# Drafts
 
-***
-
-title: Drafts
-subtitle: Preparing and scheduling Messages for your agents.
-slug: drafts
-description: >-
-Learn how to create, manage, and send Drafts to enable advanced agent
-workflows like human-in-the-loop review and scheduled sending.
---------------------------------------------------------------
+> Learn how to create, manage, and send Drafts to enable advanced agent workflows like human-in-the-loop review and scheduled sending.
 
 ## What is a Draft?
 
@@ -1568,8 +1600,8 @@ Once a `Draft` is created, you can retrieve it by its ID
   ```
 
   ```bash title="CLI"
-  # retrieve a draft by id
-  agentmail inboxes:drafts retrieve \
+  # get a draft by id
+  agentmail inboxes:drafts get \
     --inbox-id my_inbox@domain.com \
     --draft-id draft_id_123
   ```
@@ -2033,16 +2065,9 @@ Copy one of the blocks below into Cursor or Claude for complete Drafts API knowl
   ```
 </CodeBlocks>
 
+# Labels
 
-***
-
-title: Labels
-subtitle: Organizing and categorizing your agent's conversations at scale.
-slug: labels
-description: >-
-Learn how to use Labels to manage state, track campaigns, and filter messages
-for powerful agentic workflows.
--------------------------------
+> Learn how to use Labels to manage state, track campaigns, and filter messages for powerful agentic workflows.
 
 ## What are `Labels`?
 
@@ -2292,16 +2317,9 @@ Copy one of the blocks below into Cursor or Claude for complete Labels usage in
   based on their content.
 </Callout>
 
+# Lists
 
-***
-
-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.
------------------------------------
+> Learn how to use Lists to control which email addresses and domains your agents can send to or receive from.
 
 ## What are Lists?
 
@@ -2415,8 +2433,8 @@ Retrieve a specific entry from a list by its email address or domain.
   ```
 
   ```bash title="CLI"
-  # retrieve a specific entry
-  agentmail lists retrieve \
+  # get a specific entry
+  agentmail lists get \
     --direction receive \
     --type allow \
     --entry partner@example.com
@@ -2601,16 +2619,9 @@ Copy one of the blocks below into Cursor or Claude for complete Lists API knowle
   ```
 </CodeBlocks>
 
+# Attachments
 
-***
-
-title: Attachments
-subtitle: Sending and receiving files with your agents.
-slug: attachments
-description: >-
-Learn how to send files as attachments, and download incoming attachments from
-both messages and threads.
---------------------------
+> Learn how to send files as attachments, and download incoming attachments from both messages and threads.
 
 ## What are `Attachments`?
 
@@ -2835,12 +2846,9 @@ Copy one of the blocks below into Cursor or Claude for complete Attachments usag
   ```
 </CodeBlocks>
 
+# Pods
 
-***
-
-title: Pods
-description: Learn how to use pods for multi-tenant email management
---------------------------------------------------------------------
+> Learn how to use pods for multi-tenant email management
 
 ## What are Pods?
 
@@ -3131,16 +3139,9 @@ Pod: "Marketing-Agent"
 * Learn about [Inboxes](/inboxes) and how to create email accounts within pods
 * Explore [Domains](/custom-domains) to set up custom email domains for your pods
 
+# Permissions
 
-***
-
-title: Permissions
-subtitle: Control what your API keys can access with granular permissions.
-slug: permissions
-description: >-
-Learn how to configure fine-grained permissions on API keys to restrict access
-to specific resources and operations.
--------------------------------------
+> Learn how to configure fine-grained permissions on API keys to restrict access to specific resources and operations.
 
 ## What are Permissions?
 
@@ -3572,24 +3573,65 @@ Copy one of the blocks below into Cursor or Claude for complete Permissions API
 * **Combine with scopes for defense in depth.** Pair permissions with [pod-scoped](/multi-tenancy#pod-scoped-keys) or [inbox-scoped](/multi-tenancy#inbox-scoped-keys) keys. Scopes limit *which* resources a key can see, while permissions limit *what* it can do.
 * **Filter unwanted content from agents.** Set `label_spam_read`, `label_blocked_read`, and `label_trash_read` to `false` on agent-facing keys. This prevents agents from seeing or processing unwanted email, keeping their context clean.
 
+# Agent Onboarding
 
-***
-
-title: Agent Onboarding
-subtitle: Everything you need to onboard your AI agent to AgentMail
-slug: agent-onboarding
-description: >-
-Resources for AI coding assistants, MCP servers, skills, and agent-friendly
-documentation.
---------------
+> Resources for AI coding assistants, MCP servers, skills, and agent-friendly documentation.
 
 > Everything you need to onboard your AI agent to AgentMail — the email platform built for AI agents.
 
 If you're developing with AI, AgentMail offers several resources to improve your experience.
 
-## Prerequisite: Create an API Key
+## Get an API key
+
+Your agent can sign up programmatically using the Agent API. No console access needed.
+
+<CodeBlocks>
+  ```python title="Python"
+  from agentmail import AgentMail
+
+  client = AgentMail()
+  response = client.agent.sign_up(human_email="you@example.com", username="my-agent")
+  # response.api_key  -> store this securely
+  # response.inbox_id -> my-agent@agentmail.to
+  ```
+
+  ```typescript title="TypeScript"
+  import { AgentMailClient } from "agentmail";
 
-You'll need a human to create an AgentMail account at [console.agentmail.to](https://console.agentmail.to). Once you have an account, create an API key from the dashboard. With an API key, your agent can create inboxes, send and receive emails, manage threads, and more.
+  const client = new AgentMailClient();
+  const response = await client.agent.signUp({ humanEmail: "you@example.com", username: "my-agent" });
+  // response.apiKey  -> store this securely
+  // response.inboxId -> my-agent@agentmail.to
+  ```
+
+  ```bash title="CLI"
+  agentmail agent sign-up --human-email you@example.com --username my-agent
+  ```
+</CodeBlocks>
+
+A 6-digit OTP is sent to the provided email. Verify to unlock full permissions:
+
+<CodeBlocks>
+  ```python title="Python"
+  client = AgentMail(api_key=response.api_key)
+  client.agent.verify(otp_code="123456")
+  ```
+
+  ```typescript title="TypeScript"
+  const authedClient = new AgentMailClient({ apiKey: response.apiKey });
+  await authedClient.agent.verify({ otpCode: "123456" });
+  ```
+
+  ```bash title="CLI"
+  agentmail agent verify --otp-code 123456
+  ```
+</CodeBlocks>
+
+<Info>
+  The sign-up endpoint is idempotent. Calling it again with the same email rotates the API key and resends the OTP if expired.
+</Info>
+
+Alternatively, a human can create an account at [console.agentmail.to](https://console.agentmail.to) and generate an API key from the dashboard.
 
 <Info>
   AgentMail's free tier includes 3 inboxes and 3,000 emails/month. Your agent can start building immediately.
@@ -3635,19 +3677,25 @@ You can selectively enable specific tools using the `--tools` argument:
 
 ### Available MCP Tools
 
-| Tool               | Description                           |
-| ------------------ | ------------------------------------- |
-| `create_inbox`     | Create a new email inbox for an agent |
-| `list_inboxes`     | List all inboxes in your account      |
-| `get_inbox`        | Get details of a specific inbox       |
-| `delete_inbox`     | Delete an inbox                       |
-| `send_message`     | Send an email from an agent inbox     |
-| `reply_to_message` | Reply to an email in a thread         |
-| `forward_message`  | Forward an email                      |
-| `update_message`   | Update message labels or status       |
-| `list_threads`     | List email threads in an inbox        |
-| `get_thread`       | Get a full email thread with messages |
-| `get_attachment`   | Download an email attachment          |
+| Tool               | Description                                                     |
+| ------------------ | --------------------------------------------------------------- |
+| `create_inbox`     | Create a new email inbox for an agent                           |
+| `list_inboxes`     | List all inboxes in your account                                |
+| `get_inbox`        | Get details of a specific inbox                                 |
+| `delete_inbox`     | Delete an inbox                                                 |
+| `send_message`     | Send an email from an agent inbox                               |
+| `reply_to_message` | Reply to an email in a thread                                   |
+| `forward_message`  | Forward an email                                                |
+| `update_message`   | Update message labels or status                                 |
+| `create_draft`     | Create a draft email (optionally scheduled via `send_at`)       |
+| `list_drafts`      | List drafts in an inbox (filter by labels like `scheduled`)     |
+| `get_draft`        | Get a draft by ID with content and scheduled send time          |
+| `update_draft`     | Update a draft; use `send_at` to reschedule                     |
+| `send_draft`       | Send a draft immediately (draft is converted to a sent message) |
+| `delete_draft`     | Delete a draft; also cancels a scheduled send                   |
+| `list_threads`     | List email threads in an inbox                                  |
+| `get_thread`       | Get a full email thread with messages                           |
+| `get_attachment`   | Download an email attachment                                    |
 
 <Card title="MCP Server on GitHub" icon="fa-brands fa-github" href="https://github.com/agentmail-to/agentmail-smithery-mcp">
   View the source code, contribute, or report issues.
@@ -3717,19 +3765,26 @@ export AGENTMAIL_API_KEY="your-api-key-here"
   View the skill source and full documentation.
 </Card>
 
-## Quick Start for Agents
+## Quick start for agents
 
-Create an inbox and send your first email in a few lines:
+Sign up, create an inbox, and send your first email:
 
 <CodeBlocks>
   ```python title="Python"
   from agentmail import AgentMail
 
-  client = AgentMail(api_key="am_...")
+  # sign up (no API key needed)
+  client = AgentMail()
+  response = client.agent.sign_up(human_email="you@example.com", username="my-agent")
+
+  # after verifying with the OTP sent to your email:
+  client = AgentMail(api_key=response.api_key)
+  client.agent.verify(otp_code="123456")
+
+  # create an inbox and send an email
   inbox = client.inboxes.create(display_name="My AI Agent")
   print(f"Agent email: {inbox.inbox_id}")
 
-  # Send an email
   client.inboxes.messages.send(
       inbox.inbox_id,
       to="user@example.com",
@@ -3741,12 +3796,19 @@ Create an inbox and send your first email in a few lines:
   ```typescript title="TypeScript"
   import { AgentMailClient } from "agentmail";
 
-  const client = new AgentMailClient({ apiKey: "am_..." });
-  const inbox = await client.inboxes.create({ displayName: "My AI Agent" });
+  // sign up (no API key needed)
+  const client = new AgentMailClient();
+  const response = await client.agent.signUp({ humanEmail: "you@example.com", username: "my-agent" });
+
+  // after verifying with the OTP sent to your email:
+  const authedClient = new AgentMailClient({ apiKey: response.apiKey });
+  await authedClient.agent.verify({ otpCode: "123456" });
+
+  // create an inbox and send an email
+  const inbox = await authedClient.inboxes.create({ displayName: "My AI Agent" });
   console.log(`Agent email: ${inbox.inboxId}`);
 
-  // Send an email
-  await client.inboxes.messages.send(inbox.inboxId, {
+  await authedClient.inboxes.messages.send(inbox.inboxId, {
       to: "user@example.com",
       subject: "Hello from my AI agent",
       text: "Hi! I'm an AI agent with my own email address."
@@ -3754,6 +3816,10 @@ Create an inbox and send your first email in a few lines:
   ```
 
   ```bash title="CLI"
+  # sign up and verify
+  agentmail agent sign-up --human-email you@example.com --username my-agent
+  agentmail agent verify --otp-code 123456
+
   # create an inbox
   agentmail inboxes create --display-name "My AI Agent"
 
@@ -3766,6 +3832,10 @@ Create an inbox and send your first email in a few lines:
   ```
 </CodeBlocks>
 
+<Note>
+  Already have an API key? Skip the sign-up step and initialize the client directly with your key.
+</Note>
+
 ### Receive and reply to emails
 
 <CodeBlocks>
@@ -3791,17 +3861,17 @@ Create an inbox and send your first email in a few lines:
 
   ```typescript title="TypeScript"
   // List threads in the inbox
-  const threads = await client.inboxes.threads.list(inbox.inboxId);
+  const threads = await authedClient.inboxes.threads.list(inbox.inboxId);
 
   // Get the latest thread
-  const thread = await client.inboxes.threads.get(
+  const thread = await authedClient.inboxes.threads.get(
       inbox.inboxId,
       threads.threads[0].threadId
   );
 
   // Reply to the latest message
   const latestMessage = thread.messages[thread.messages.length - 1];
-  await client.inboxes.messages.reply(
+  await authedClient.inboxes.messages.reply(
       inbox.inboxId,
       latestMessage.messageId,
       { to: [latestMessage.from], text: "Thanks for your email! I'll look into this." }
@@ -3866,16 +3936,9 @@ Unlike traditional email APIs that are built for one-way transactional email, Ag
   </Card>
 </CardGroup>
 
+# Skills
 
-***
-
-title: Skills
-subtitle: Add AgentMail to AI coding assistants with the official skill
-slug: integrations/skills
-description: >-
-AgentMail's official skill for OpenClaw, Claude Code, Cursor, and other AI
-assistants
-----------
+> AgentMail's official skill for OpenClaw, Claude Code, Cursor, and other AI assistants
 
 ## Getting started
 
@@ -3999,14 +4062,9 @@ Once installed, you can ask your AI assistant to perform email tasks:
 * [AgentMail API Reference](/api-reference)
 * [AgentMail Console](https://console.agentmail.to)
 
+# MCP
 
-***
-
-title: MCP
-subtitle: Connect AgentMail to any MCP-compatible AI client
-slug: integrations/mcp
-description: AgentMail's Model Context Protocol (MCP) integration
------------------------------------------------------------------
+> AgentMail's Model Context Protocol (MCP) integration
 
 ## Getting started
 
@@ -4017,10 +4075,10 @@ The Model Context Protocol (MCP) is an open standard that enables AI application
 Install with:
 
 ```bash
-npx add-mcp https://mcp.agentmail.to
+npx add-mcp https://mcp.agentmail.to/mcp
 ```
 
-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).
+Configure your API key when prompted. Get your key from the [AgentMail Console](https://console.agentmail.to). For more details, visit [mcp.agentmail.to/mcp](https://mcp.agentmail.to/mcp).
 
 ## Features
 
@@ -4028,6 +4086,7 @@ The AgentMail MCP server provides tools for:
 
 * **Inbox management:** Create, list, and delete inboxes
 * **Message operations:** Send, receive, and reply to emails
+* **Drafts:** Create, schedule, update, and send draft emails
 * **Thread management:** Access and manage email threads
 * **Attachments:** Handle email attachments
 
@@ -4040,16 +4099,11 @@ The AgentMail MCP server works with any MCP-compatible client, including:
 * Windsurf
 * Other MCP-enabled AI applications
 
-For detailed setup instructions and available tools, visit [mcp.agentmail.to](https://mcp.agentmail.to).
+For detailed setup instructions and available tools, visit [mcp.agentmail.to/mcp](https://mcp.agentmail.to/mcp).
 
+# CLI
 
-***
-
-title: CLI
-subtitle: Manage AgentMail resources from the command line
-slug: integrations/cli
-description: AgentMail's official command-line interface
---------------------------------------------------------
+> AgentMail's official command-line interface
 
 ## Getting started
 
@@ -4119,7 +4173,7 @@ agentmail webhooks create \
 The CLI provides commands for:
 
 * **Inbox management:** Create, list, update, and delete inboxes
-* **Message operations:** Send, reply, forward, and retrieve emails
+* **Message operations:** Send, reply, forward, and read emails
 * **Thread management:** List and manage email threads
 * **Drafts:** Create, update, send, and delete drafts
 * **Webhooks:** Create and manage webhook endpoints
@@ -4159,14 +4213,9 @@ openclaw skills install agentmail-to/agentmail-skills/agentmail-cli
 
 This works with any compatible tool, including OpenClaw, Claude Code, Cursor, and Codex. See the [Skills](/integrations/skills) page for more details.
 
+# Google ADK
 
-***
-
-title: Google ADK
-subtitle: Give your Google ADK agent its own email inbox
-slug: integrations/google-adk
-description: AgentMail's Google Agent Development Kit (ADK) integration
------------------------------------------------------------------------
+> AgentMail's Google Agent Development Kit (ADK) integration
 
 ## Getting started
 
@@ -4277,14 +4326,20 @@ Once connected, your ADK agent has access to the following AgentMail tools:
 | `forward_message`  | Forward a message to another recipient        |
 | `update_message`   | Update message properties such as read status |
 
+### Draft management
 
-***
+| Tool           | Description                                               |
+| -------------- | --------------------------------------------------------- |
+| `create_draft` | Create a draft email (optionally scheduled via `send_at`) |
+| `list_drafts`  | List drafts in an inbox                                   |
+| `get_draft`    | Get a specific draft by ID                                |
+| `update_draft` | Update a draft or reschedule a scheduled send             |
+| `send_draft`   | Send a draft immediately                                  |
+| `delete_draft` | Delete a draft or cancel a scheduled send                 |
+
+# OpenClaw
 
-title: OpenClaw
-subtitle: Give your OpenClaw agent its own email inbox
-slug: integrations/openclaw
-description: AgentMail's OpenClaw integration
----------------------------------------------
+> AgentMail's OpenClaw integration
 
 ## Getting started
 
@@ -4505,14 +4560,9 @@ Now OpenClaw will be notified whenever a new email arrives, allowing it to proac
 * [OpenClaw Documentation](https://docs.openclaw.ai)
 * [OpenClaw Skills Guide](https://docs.openclaw.ai/tools/skills)
 
+# Replit
 
-***
-
-title: Replit
-subtitle: Integrate AgentMail with your Replit apps and agents
-slug: integrations/replit
-description: AgentMail's Replit integration
--------------------------------------------
+> AgentMail's Replit integration
 
 ## Getting started
 
@@ -4721,14 +4771,9 @@ 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.
 
+# x402
 
-***
-
-title: x402
-subtitle: Pay-per-use AgentMail with the x402 payment protocol
-slug: integrations/x402
-description: AgentMail's x402 integration for HTTP-native payments
-------------------------------------------------------------------
+> AgentMail's x402 integration for HTTP-native payments
 
 ## Getting started
 
@@ -4883,14 +4928,9 @@ This means your agent can use the full AgentMail API (inboxes, messages, threads
 * [AgentMail API reference](/api-reference)
 * [WebSockets overview](/websockets)
 
+# MPP
 
-***
-
-title: MPP
-subtitle: Pay-per-use AgentMail with Stripe's Machine Payments Protocol
-slug: integrations/mpp
-description: AgentMail's MPP integration for machine-to-machine payments via Stripe
------------------------------------------------------------------------------------
+> AgentMail's MPP integration for machine-to-machine payments via Stripe
 
 ## Getting started
 
@@ -4978,14 +5018,9 @@ This means your agent can use the full AgentMail API (inboxes, messages, threads
 * [AgentMail API reference](/api-reference)
 * [WebSockets overview](/websockets)
 
+# Integrate LiveKit Agents
 
-***
-
-title: Integrate LiveKit Agents
-subtitle: Build a voice assistant with real time email capabilities.
-slug: integrate-livekit-agents
-description: A step-by-step guide to integrate with the LiveKit Agents SDK.
----------------------------------------------------------------------------
+> A step-by-step guide to integrate with the LiveKit Agents SDK.
 
 ## Overview
 
@@ -5112,14 +5147,9 @@ Run your agent inside the terminal and send it an email
 python agent.py console
 ```
 
+# Sim.ai
 
-***
-
-title: Sim.ai
-subtitle: Connect AgentMail to your Sim.ai workflows
-slug: integrations/sim
-description: AgentMail's Sim.ai integration
--------------------------------------------
+> AgentMail's Sim.ai integration
 
 ## Getting started
 
@@ -5188,16 +5218,9 @@ Once connected, Sim provides access to the following AgentMail operations:
 * [AgentMail API reference](/api-reference)
 * [Webhooks overview](/webhooks/webhooks-overview)
 
+# Guide: Sending & Receiving Email
 
-***
-
-title: 'Guide: Sending & Receiving Email'
-subtitle: Building your first conversational agent workflow.
-slug: sending-receiving-email
-description: >-
-A step-by-step guide to the practical workflow of sending initial emails and
-handling replies to have a full conversation.
----------------------------------------------
+> A step-by-step guide to the practical workflow of sending initial emails and handling replies to have a full conversation.
 
 This guide walks you through the complete, practical workflow of an agent having a conversation. While the `Core Concepts` pages detail the individual API calls, this guide shows you how to stitch them together to create a functional conversational loop.
 
@@ -5344,7 +5367,7 @@ Here's the step-by-step logic for a polling-based conversational agent.
 <Callout intent="success" title="Real-Time Processing with Webhooks">
   For production applications, polling is inefficient. The best way to handle incoming replies is to use `Webhooks`. This allows AgentMail to notify your agent instantly when a new `Message` arrives, so you can reply in real-time.
 
-  [**Learn how to set up `Webhooks` →**](/overview)
+  [**Learn how to set up `Webhooks` →**](/webhooks-overview)
 </Callout>
 
 ## Scheduling Emails
@@ -5393,16 +5416,9 @@ Create a `Draft` with the `send_at` field and AgentMail handles the rest. The em
   For more details on scheduled sending—including how to cancel, reschedule, list scheduled drafts, and build conditional follow-up workflows—see the [**Drafts**](/drafts) page.
 </Callout>
 
+# IMAP & SMTP
 
-***
-
-title: IMAP & SMTP
-subtitle: Connect to AgentMail with standard email protocols
-slug: imap-smtp
-description: >-
-Configure IMAP and SMTP to access your AgentMail inboxes using email clients
-or programmatic access.
------------------------
+> Configure IMAP and SMTP to access your AgentMail inboxes using email clients or programmatic access.
 
 <Callout intent="warn" title="IMAP is Under Development">
   IMAP support is currently under development and will be available in the coming weeks. The documentation below describes the planned functionality. SMTP is fully available today.
@@ -5641,16 +5657,9 @@ sendEmail().catch(console.error);
 | Access to all folders       | API            |
 | Bulk operations             | API            |
 
+# Guide: Multi-Tenancy
 
-***
-
-title: 'Guide: Multi-Tenancy'
-subtitle: 'Pods, scoped keys, and event routing for your customers.'
-slug: multi-tenancy
-description: >-
-How to use pods, scoped API keys, and webhook filtering to build multi-tenant
-email on AgentMail.
--------------------
+> How to use pods, scoped API keys, and webhook filtering to build multi-tenant email on AgentMail.
 
 If you're building a platform where each of your customers needs their own email infrastructure, this is how you set it up. The basic idea: create a `Pod` per customer, give them a scoped API key, and route webhook events to the right place.
 
@@ -5936,18 +5945,9 @@ Here's what onboarding a new tenant looks like end to end:
   ```
 </CodeBlocks>
 
+# Using Custom Domains
 
-***
-
-title: Using Custom Domains
-subtitle: >-
-Strengthen your agent's identity and improve deliverability with your own
-domain.
-slug: custom-domains
-description: >-
-A step-by-step guide to configuring your custom domain with AgentMail for
-enhanced branding and trust.
-----------------------------
+> A step-by-step guide to configuring your custom domain with AgentMail for enhanced branding and trust.
 
 ## Why Use a Custom Domain?
 
@@ -6346,18 +6346,9 @@ DNS can be tricky. Here are some common issues and how to resolve them.
 
 Check out our guide on [Email Deliverability](/email-deliverability) for tips on warming up your new domain and maintaining a healthy sender reputation.
 
+# Managing Your Domains
 
-***
-
-title: Managing Your Domains
-subtitle: >-
-Best practices for monitoring, scaling, and optimizing your domain strategy
-for agent fleets.
-slug: managing-domains
-description: >-
-Learn how to manage your custom domains effectively using AgentMail's API for
-enhanced deliverability and reputation management.
---------------------------------------------------
+> Learn how to manage your custom domains effectively using AgentMail's API for enhanced deliverability and reputation management.
 
 ## From Setup to Strategy
 
@@ -6425,16 +6416,9 @@ By default, AgentMail configures your domain with a strict DMARC policy (`p=reje
 
 However, this is obviously up to your discretion if you want to impose a more relaxed DMARC policy, whether its `p=none` where it doesn't do anything if both SPF and DMARC fail, or its `p=quarantine`, where it puts the mail in spam/junk. Feel free to do more research at your own discretion. You can do this by changing the value in the TXT record in your DNS configuration where the name starts with `_dmarc`.
 
+# Webhooks Overview
 
-***
-
-title: Webhooks Overview
-subtitle: Get real-time notifications for email events.
-slug: overview
-description: >-
-Learn how to use Webhooks to build responsive, event-driven email agents with
-AgentMail.
-----------
+> Learn how to use Webhooks to build responsive, event-driven email agents with AgentMail.
 
 Webhooks are the best way to get real-time information about what's happening with your emails. Instead of constantly asking the AgentMail API if there's a new email (a process called polling), you can register a URL, and we will send you a `POST` request with the details as soon as an event happens.
 
@@ -6445,6 +6429,10 @@ 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.
 
+<Callout intent="info" title="Prefer a simpler setup?">
+  If you don't want to expose a public URL or set up ngrok, [WebSockets](/websockets) let you receive the same events over a persistent connection with no external tooling required.
+</Callout>
+
 ## Available Events
 
 AgentMail supports nine 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.
@@ -6545,7 +6533,7 @@ Omitted content is always available through the API. After receiving a webhook,
 
   ```bash title="CLI"
   # fetch the full message after receiving a webhook
-  agentmail inboxes:messages retrieve \
+  agentmail inboxes:messages get \
     --inbox-id <inbox_id> \
     --message-id <message_id>
   ```
@@ -6687,18 +6675,17 @@ Copy one of the blocks below into Cursor or Claude for complete Webhooks API kno
     Learn how to verify webhook signatures to secure your endpoints.
   </Card>
 
+  <Card title="WebSockets" href="/websockets">
+    Receive events over a persistent connection with no public URL required.
+  </Card>
+
   <Card title="Example: Event-Driven Agent" href="/github-star-agent">
     Build a fully deployable, event-driven agent that can respond to emails in
     real time.
   </Card>
 </CardGroup>
 
-
-***
-
-title: Webhook Events
-slug: events
-------------
+# Webhook Events
 
 As mentioned in the overview, webhooks allow us to create event-driven applications.
 
@@ -7241,16 +7228,9 @@ For example, if you only need to trigger workflows on incoming messages, you can
 
 If you have any specific webhook notifications you would like, please ping us in the `#feature-requests` channel in the [Discord](https://discord.gg/hTYatWYWBc)
 
+# Webhook Setup Guide
 
-***
-
-title: Webhook Setup Guide
-subtitle: Step-by-step guide to configure webhooks.
-slug: webhook-setup
-description: >-
-A comprehensive guide to setting up webhooks with ngrok and AgentMail,
-including account creation, inbox setup, and code examples.
------------------------------------------------------------
+> A comprehensive guide to setting up webhooks with ngrok and AgentMail, including account creation, inbox setup, and code examples.
 
 This guide walks you through the complete process of setting up webhooks to receive real-time notifications from AgentMail. You'll learn how to create an ngrok account, set up an inbox, configure webhooks, and write a simple webhook receiver.
 
@@ -7263,6 +7243,10 @@ Before you start, make sure you have:
 * `pip` package manager
 * Basic familiarity with Python and terminal commands
 
+<Callout intent="info" title="Want something simpler?">
+  Webhooks require a public URL and tools like ngrok. If you'd rather skip that setup, [WebSockets](/websockets) give you real-time events over a persistent connection with no external tooling. See the [WebSockets quickstart](/websockets/quickstart).
+</Callout>
+
 ## Installation
 
 First, install the required Python packages:
@@ -7545,7 +7529,7 @@ For production deployments:
     Learn how to verify webhook signatures for secure endpoints.
   </Card>
 
-  <Card title="Webhooks Overview" href="/overview">
+  <Card title="Webhooks Overview" href="/webhooks-overview">
     Learn more about how webhooks work and their payload structure.
   </Card>
 
@@ -7554,16 +7538,9 @@ For production deployments:
   </Card>
 </CardGroup>
 
+# Verifying Webhooks
 
-***
-
-title: Verifying Webhooks
-subtitle: Ensure webhook requests are authentically from AgentMail.
-slug: webhook-verification
-description: >-
-Learn how to verify webhook signatures to secure your webhook endpoints and
-prevent spoofed requests.
--------------------------
+> Learn how to verify webhook signatures to secure your webhook endpoints and prevent spoofed requests.
 
 When building webhook receivers, it's critical to verify that incoming requests actually originate from AgentMail and haven't been tampered with. AgentMail uses [Svix](https://www.svix.com/) to deliver webhooks, which provides cryptographic signature verification.
 
@@ -7610,7 +7587,7 @@ Each webhook endpoint has a unique signing secret that you'll use to verify requ
 
   ```bash title="CLI"
   # get webhook details including the signing secret
-  agentmail webhooks retrieve --webhook-id ep_xxx
+  agentmail webhooks get --webhook-id ep_xxx
   ```
 </CodeBlocks>
 
@@ -8006,16 +7983,9 @@ For production, you'll need to deploy your webhook server to a hosting provider
   </Card>
 </CardGroup>
 
+# WebSockets
 
-***
-
-title: WebSockets
-subtitle: 'Real-time, low-latency email event streaming'
-slug: websockets
-description: >-
-Learn how to use WebSockets for instant email notifications without webhooks
-or polling.
------------
+> Learn how to use WebSockets for instant email notifications without webhooks or polling.
 
 WebSockets provide a persistent, bidirectional connection to AgentMail for receiving email events in real-time. Unlike webhooks, WebSockets don't require a public URL or external tools like ngrok.
 
@@ -8458,13 +8428,7 @@ Copy one of the blocks below into Cursor or Claude for WebSockets in one shot.
 
 ***
 
-
-***
-
-title: WebSockets Quickstart
-subtitle: Get started with real-time email event streaming
-slug: websockets/quickstart
----------------------------
+# WebSockets Quickstart
 
 ## Copy for Cursor / Claude
 
@@ -8552,16 +8516,9 @@ with client.websockets.connect() as socket:
             print(f"Received message from: {msg.from_}")
 ```
 
+# Email Deliverability
 
-***
-
-title: Email Deliverability
-subtitle: 'Best practices for landing your emails in the inbox, not the spam folder.'
-slug: email-deliverability
-description: >-
-Learn the strategies and best practices for maximizing your email
-deliverability with AgentMail.
-------------------------------
+> Learn the strategies and best practices for maximizing your email deliverability with AgentMail.
 
 ## What is Email Deliverability?
 
@@ -8667,16 +8624,9 @@ The content of your email plays a huge role in whether it's seen as a valuable m
   </Step>
 </Steps>
 
+# Idempotent Requests
 
-***
-
-title: Idempotent Requests
-subtitle: Learn how to use idempotency keys to build safe and reliable API integrations.
-slug: idempotency
-description: >-
-A guide to using the client\_id parameter in AgentMail to prevent duplicate
-resources and safely retry API requests.
-----------------------------------------
+> A guide to using the client_id parameter in AgentMail to prevent duplicate resources and safely retry API requests.
 
 ## What is Idempotency?
 
@@ -8722,18 +8672,9 @@ To use idempotency effectively, the `client_id` you generate must be unique and
 
 A common and highly effective pattern is to generate a UUID (like a `UUID v4`) on your client side for a resource you are about to create, save that UUID in your own database, and then use it as the `client_id` in the API call. This gives you a reliable key to use for any retries.
 
+# Example: Event-Driven Agent
 
-***
-
-title: 'Example: Event-Driven Agent'
-subtitle: >-
-Build a proactive, event-driven GitHub agent that uses Webhooks to handle
-replies in real time.
-slug: webhook-agent
-description: >-
-A step-by-step guide to building a sophisticated agent that performs proactive
-outreach and uses webhooks for inbound message processing.
-----------------------------------------------------------
+> A step-by-step guide to building a sophisticated agent that performs proactive outreach and uses webhooks for inbound message processing.
 
 This tutorial walks you through building a sophisticated, dual-mode agent. It will:
 
@@ -9141,14 +9082,9 @@ You now have a fully event-driven agent that can both initiate conversations and
 ```
 ```
 
+# Auto-Reply Email Agent
 
-***
-
-title: Auto-Reply Email Agent
-description: >-
-Build a simple agent that automatically responds to incoming emails with
-personalized messages
----------------------
+> Build a simple agent that automatically responds to incoming emails with personalized messages
 
 ## Overview
 
@@ -10013,14 +9949,9 @@ Your agent now has conversation memory. When replying to follow-up emails, the A
 
 If you build something cool with AgentMail, we'd love to hear about it. Share in our [Discord community](https://discord.gg/hTYatWYWBc)!
 
+# Smart Email Labeling Agent
 
-***
-
-title: Smart Email Labeling Agent
-description: >-
-Build an AI-powered agent that automatically classifies and labels incoming
-emails across multiple dimensions
----------------------------------
+> Build an AI-powered agent that automatically classifies and labels incoming emails across multiple dimensions
 
 ## Overview
 
@@ -10729,15 +10660,9 @@ Use this data to identify bottlenecks, improve processes, and make data-driven d
 
 Congratulations! You've built an AI-powered email classification system. This agent showcases how AgentMail's labeling feature can power sophisticated inbox automation and analytics.
 
+# Sales Agent with WebSocket
 
-***
-
-title: Sales Agent with WebSocket
-slug: sales-agent-websocket
-description: >-
-A step-by-step guide to building an AI-powered sales agent that uses WebSocket
-for real-time email processing without polling or webhooks.
------------------------------------------------------------
+> A step-by-step guide to building an AI-powered sales agent that uses WebSocket for real-time email processing without polling or webhooks.
 
 ## Overview
 
@@ -11455,7 +11380,6 @@ await socket.send_subscribe(Subscribe(inbox_ids=[
 
 If you build something cool with AgentMail, we'd love to hear about it. Share in our [Discord community](https://discord.gg/hTYatWYWBc)!
 
-
 # Live Email Agents
 
 We have several deployed agents running in production that demonstrate the power of AgentMail. These agents showcase different use cases and capabilities of our platform.
@@ -11497,15 +11421,9 @@ Ready to build your own intelligent email agent? Check out our [quickstart guide
   demo.
 </Note>
 
+# Frequently Asked Questions (FAQ)
 
-***
-
-title: Frequently Asked Questions (FAQ)
-slug: faq
-description: >-
-Find answers to common questions about AgentMail, from core concepts to best
-practices and security.
------------------------
+> Find answers to common questions about AgentMail, from core concepts to best practices and security.
 
 <AccordionGroup>
   <Accordion title="What is AgentMail?">
@@ -11537,7 +11455,7 @@ practices and security.
     For production applications, **Webhooks are the recommended method**. They
     provide real-time notifications and are far more efficient than constantly
     polling the API for new messages. You can learn how to set them up in our
-    [Webhooks Overview](/overview).
+    [Webhooks Overview](/webhooks-overview).
   </Accordion>
 
   <Accordion title="How do I get just the new content from a reply?">
@@ -11557,16 +11475,9 @@ practices and security.
   </Accordion>
 </AccordionGroup>
 
+# Email Reply Extraction with Talon
 
-***
-
-title: Email Reply Extraction with Talon
-subtitle: Extract clean reply content from email threads using Talon library
-slug: talon-reply-extraction
-description: >-
-Learn how to use Talon to extract new content from email replies, removing
-quoted text with 93.8% accuracy.
---------------------------------
+> Learn how to use Talon to extract new content from email replies, removing quoted text with 93.8% accuracy.
 
 ## Why Talon?
 
@@ -12096,15 +12007,9 @@ TalonJS provides 90.6% accuracy with slightly faster performance (1.88ms), makin
   * The 3.2% accuracy difference is acceptable for most use cases
 </Tip>
 
+# Join the AgentMail Community
 
-***
-
-title: Join the AgentMail Community
-slug: community
-description: >-
-Connect with the AgentMail team and developers, share what you're building,
-and get support.
-----------------
+> Connect with the AgentMail team and developers, share what you're building, and get support.
 
 <CardGroup>
   <Card title="Join our Discord Server" href="https://discord.com/invite/hTYatWYWBc" icon="fa-brands fa-discord">
@@ -12129,13 +12034,9 @@ and get support.
   To learn more about our premium plans and dedicated support options, please visit our website [here](https://agentmail.to/pricing).
 </Callout>
 
+# Support
 
-***
-
-title: Support
-slug: support
-description: Get help with AgentMail through our support channels.
-------------------------------------------------------------------
+> Get help with AgentMail through our support channels.
 
 ## Need Help?
 
@@ -12147,13 +12048,9 @@ description: Get help with AgentMail through our support channels.
   <Card title="Email Support" icon="fa-solid fa-envelope" href="mailto:support@agentmail.cc" />
 </Cards>
 
+# Understanding Email Authentication (SPF, DKIM, DMARC)
 
-***
-
-title: 'Understanding Email Authentication (SPF, DKIM, DMARC)'
-slug: email-protocols
-description: 'Learn why we ask for DNS records and what SPF, DKIM, and DMARC are.'
-----------------------------------------------------------------------------------
+> Learn why we ask for DNS records and what SPF, DKIM, and DMARC are.
 
 When you add a custom domain to AgentMail, we ask you to add several records to your DNS settings. We understand that this can seem daunting, and we want to be completely transparent about what these records are and why they are necessary.
 
@@ -12226,14 +12123,9 @@ This is some records that we might give you:
 
 We hope this provides a clear and transparent look into why these DNS records are required. By setting them up, you enable AgentMail to provide a secure and reliable email experience for your AI agents.
 
+# SOC 2 Compliance
 
-***
-
-title: SOC 2 Compliance
-description: AgentMail's SOC 2 Type I and Type II compliance.
-sidebar\_position: 40
-lastUpdated: '2026-03-17'
--------------------------
+> AgentMail's SOC 2 Type I and Type II compliance.
 
 > AgentMail has achieved **SOC 2 Type I** (July 2025) and **Type II** (Q1 2026) compliance.
 
@@ -12361,13 +12253,9 @@ Organizations evaluating AgentMail can [request SOC 2 documentation](mailto:secu
 
 ***
 
+# Spam & Virus Detection
 
-***
-
-title: Spam & Virus Detection
-slug: spam-virus-detection
-description: How AgentMail automatically scans incoming emails for spam and viruses.
-------------------------------------------------------------------------------------
+> How AgentMail automatically scans incoming emails for spam and viruses.
 
 AgentMail automatically scans every inbound message for spam and viruses before it reaches your inbox. This happens transparently — there is nothing you need to configure.
 
@@ -12418,14 +12306,9 @@ Each thread object includes a `spam` label indicating whether it was flagged as
 }
 ```
 
+# API Welcome
 
-***
-
-title: API Welcome
-subtitle: Getting Started with AgentMail
-slug: api-reference
-description: Quick overview of the AgentMail SDK
-------------------------------------------------
+> Quick overview of the AgentMail SDK
 
 ## Introduction
 
@@ -12463,7 +12346,6 @@ If you have any other languages you would like us to support, please [reach out
 
 All of our SDKs are open source and available under the MIT license.
 
-
 # Sign Up
 
 POST https://api.agentmail.to/v0/agent/sign-up
@@ -13295,7 +13177,7 @@ GET https://api.agentmail.to/v0/inboxes/{inbox_id}
 
 **CLI:**
 ```bash
-agentmail inboxes retrieve --inbox-id <inbox_id>
+agentmail inboxes get --inbox-id <inbox_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/inboxes/get
@@ -13315,7 +13197,7 @@ paths:
       description: |-
         **CLI:**
         ```bash
-        agentmail inboxes retrieve --inbox-id <inbox_id>
+        agentmail inboxes get --inbox-id <inbox_id>
         ```
       tags:
         - subpackage_inboxes
@@ -14871,7 +14753,7 @@ GET https://api.agentmail.to/v0/inboxes/{inbox_id}/threads/{thread_id}
 
 **CLI:**
 ```bash
-agentmail inboxes:threads retrieve --inbox-id <inbox_id> --thread-id <thread_id>
+agentmail inboxes:threads get --inbox-id <inbox_id> --thread-id <thread_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/inboxes/threads/get
@@ -14893,7 +14775,7 @@ paths:
 
         ```bash
 
-        agentmail inboxes:threads retrieve --inbox-id <inbox_id> --thread-id
+        agentmail inboxes:threads get --inbox-id <inbox_id> --thread-id
         <thread_id>
 
         ```
@@ -16811,7 +16693,7 @@ GET https://api.agentmail.to/v0/inboxes/{inbox_id}/messages/{message_id}
 
 **CLI:**
 ```bash
-agentmail inboxes:messages retrieve --inbox-id <inbox_id> --message-id <message_id>
+agentmail inboxes:messages get --inbox-id <inbox_id> --message-id <message_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/inboxes/messages/get
@@ -16833,7 +16715,7 @@ paths:
 
         ```bash
 
-        agentmail inboxes:messages retrieve --inbox-id <inbox_id> --message-id
+        agentmail inboxes:messages get --inbox-id <inbox_id> --message-id
         <message_id>
 
         ```
@@ -20433,7 +20315,7 @@ GET https://api.agentmail.to/v0/inboxes/{inbox_id}/drafts/{draft_id}
 
 **CLI:**
 ```bash
-agentmail inboxes:drafts retrieve --inbox-id <inbox_id> --draft-id <draft_id>
+agentmail inboxes:drafts get --inbox-id <inbox_id> --draft-id <draft_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/inboxes/drafts/get
@@ -20450,14 +20332,10 @@ paths:
     get:
       operationId: get
       summary: Get Draft
-      description: >-
+      description: |-
         **CLI:**
-
         ```bash
-
-        agentmail inboxes:drafts retrieve --inbox-id <inbox_id> --draft-id
-        <draft_id>
-
+        agentmail inboxes:drafts get --inbox-id <inbox_id> --draft-id <draft_id>
         ```
       tags:
         - subpackage_inboxes.subpackage_inboxes/drafts
@@ -22967,7 +22845,7 @@ GET https://api.agentmail.to/v0/inboxes/{inbox_id}/lists/{direction}/{type}/{ent
 
 **CLI:**
 ```bash
-agentmail inboxes:lists retrieve --inbox-id <inbox_id> --direction <direction> --type <type> --entry <entry>
+agentmail inboxes:lists get --inbox-id <inbox_id> --direction <direction> --type <type> --entry <entry>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/inboxes/lists/get
@@ -22989,7 +22867,7 @@ paths:
 
         ```bash
 
-        agentmail inboxes:lists retrieve --inbox-id <inbox_id> --direction
+        agentmail inboxes:lists get --inbox-id <inbox_id> --direction
         <direction> --type <type> --entry <entry>
 
         ```
@@ -24168,6 +24046,340 @@ let dataTask = session.dataTask(with: request as URLRequest, completionHandler:
 dataTask.resume()
 ```
 
+# List Inbox Events
+
+GET https://api.agentmail.to/v0/inboxes/{inbox_id}/events
+
+List label change events for an inbox. Returns events in reverse chronological order by default. Use for IMAP UID projection or audit logging.
+
+**CLI:**
+```bash
+agentmail inboxes:events list --inbox-id <inbox_id>
+```
+
+Reference: https://docs.agentmail.to/api-reference/inboxes/events/list
+
+## OpenAPI Specification
+
+```yaml
+openapi: 3.1.0
+info:
+  title: api
+  version: 1.0.0
+paths:
+  /v0/inboxes/{inbox_id}/events:
+    get:
+      operationId: list
+      summary: List Inbox Events
+      description: >-
+        List label change events for an inbox. Returns events in reverse
+        chronological order by default. Use for IMAP UID projection or audit
+        logging.
+
+
+        **CLI:**
+
+        ```bash
+
+        agentmail inboxes:events list --inbox-id <inbox_id>
+
+        ```
+      tags:
+        - subpackage_inboxes.subpackage_inboxes/events
+      parameters:
+        - name: inbox_id
+          in: path
+          required: true
+          schema:
+            $ref: '#/components/schemas/type_inboxes:InboxId'
+        - name: limit
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/type_:Limit'
+        - name: page_token
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/type_:PageToken'
+        - name: ascending
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/type_:Ascending'
+        - name: Authorization
+          in: header
+          description: Bearer authentication
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Response with status 200
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/type_inbox-events:ListInboxEventsResponse'
+        '404':
+          description: Error response with status 404
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/type_:ErrorResponse'
+servers:
+  - url: https://api.agentmail.to
+  - url: https://x402.api.agentmail.to
+  - url: https://mpp.api.agentmail.to
+  - url: https://api.agentmail.eu
+components:
+  schemas:
+    type_inboxes:InboxId:
+      type: string
+      description: The ID of the inbox.
+      title: InboxId
+    type_:Limit:
+      type: integer
+      description: Limit of number of items returned.
+      title: Limit
+    type_:PageToken:
+      type: string
+      description: Page token for pagination.
+      title: PageToken
+    type_:Ascending:
+      type: boolean
+      description: Sort in ascending temporal order.
+      title: Ascending
+    type_:Count:
+      type: integer
+      description: Number of items returned.
+      title: Count
+    type_:OrganizationId:
+      type: string
+      description: ID of organization.
+      title: OrganizationId
+    type_inbox-events:InboxEventId:
+      type: string
+      description: ID of event.
+      title: InboxEventId
+    type_inbox-events:InboxEventType:
+      type: string
+      enum:
+        - label_added
+        - label_removed
+      description: Type of inbox event.
+      title: InboxEventType
+    type_inbox-events:InboxEvent:
+      type: object
+      properties:
+        organization_id:
+          $ref: '#/components/schemas/type_:OrganizationId'
+        pod_id:
+          type: string
+          description: ID of pod.
+        inbox_id:
+          $ref: '#/components/schemas/type_inboxes:InboxId'
+        event_id:
+          $ref: '#/components/schemas/type_inbox-events:InboxEventId'
+        event_type:
+          $ref: '#/components/schemas/type_inbox-events:InboxEventType'
+        message_id:
+          type: string
+          description: ID of message.
+        label:
+          type: string
+          description: Label added or removed.
+        event_at:
+          type: string
+          format: date-time
+          description: Time at which the event occurred.
+        created_at:
+          type: string
+          format: date-time
+          description: Time at which the event was recorded.
+      required:
+        - organization_id
+        - pod_id
+        - inbox_id
+        - event_id
+        - event_type
+        - message_id
+        - label
+        - event_at
+        - created_at
+      title: InboxEvent
+    type_inbox-events:ListInboxEventsResponse:
+      type: object
+      properties:
+        count:
+          $ref: '#/components/schemas/type_:Count'
+        limit:
+          $ref: '#/components/schemas/type_:Limit'
+        next_page_token:
+          $ref: '#/components/schemas/type_:PageToken'
+        events:
+          type: array
+          items:
+            $ref: '#/components/schemas/type_inbox-events:InboxEvent'
+          description: Ordered by `event_id` descending.
+      required:
+        - count
+        - events
+      title: ListInboxEventsResponse
+    type_:ErrorName:
+      type: string
+      description: Name of error.
+      title: ErrorName
+    type_:ErrorMessage:
+      type: string
+      description: Error message.
+      title: ErrorMessage
+    type_:ErrorResponse:
+      type: object
+      properties:
+        name:
+          $ref: '#/components/schemas/type_:ErrorName'
+        message:
+          $ref: '#/components/schemas/type_:ErrorMessage'
+      required:
+        - name
+        - message
+      title: ErrorResponse
+  securitySchemes:
+    Bearer:
+      type: http
+      scheme: bearer
+
+```
+
+## SDK Code Examples
+
+```typescript
+import { AgentMailClient } from "agentmail";
+
+async function main() {
+    const client = new AgentMailClient({
+        apiKey: "YOUR_TOKEN_HERE",
+    });
+    await client.inboxes.events.list("inbox_id", {});
+}
+main();
+
+```
+
+```python
+from agentmail import AgentMail
+
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE",
+)
+
+client.inboxes.events.list(
+    inbox_id="inbox_id",
+)
+
+```
+
+```go
+package main
+
+import (
+	"fmt"
+	"net/http"
+	"io"
+)
+
+func main() {
+
+	url := "https://api.agentmail.to/v0/inboxes/inbox_id/events"
+
+	req, _ := http.NewRequest("GET", url, nil)
+
+	req.Header.Add("Authorization", "Bearer <api_key>")
+
+	res, _ := http.DefaultClient.Do(req)
+
+	defer res.Body.Close()
+	body, _ := io.ReadAll(res.Body)
+
+	fmt.Println(res)
+	fmt.Println(string(body))
+
+}
+```
+
+```ruby
+require 'uri'
+require 'net/http'
+
+url = URI("https://api.agentmail.to/v0/inboxes/inbox_id/events")
+
+http = Net::HTTP.new(url.host, url.port)
+http.use_ssl = true
+
+request = Net::HTTP::Get.new(url)
+request["Authorization"] = 'Bearer <api_key>'
+
+response = http.request(request)
+puts response.read_body
+```
+
+```java
+import com.mashape.unirest.http.HttpResponse;
+import com.mashape.unirest.http.Unirest;
+
+HttpResponse<String> response = Unirest.get("https://api.agentmail.to/v0/inboxes/inbox_id/events")
+  .header("Authorization", "Bearer <api_key>")
+  .asString();
+```
+
+```php
+<?php
+require_once('vendor/autoload.php');
+
+$client = new \GuzzleHttp\Client();
+
+$response = $client->request('GET', 'https://api.agentmail.to/v0/inboxes/inbox_id/events', [
+  'headers' => [
+    'Authorization' => 'Bearer <api_key>',
+  ],
+]);
+
+echo $response->getBody();
+```
+
+```csharp
+using RestSharp;
+
+var client = new RestClient("https://api.agentmail.to/v0/inboxes/inbox_id/events");
+var request = new RestRequest(Method.GET);
+request.AddHeader("Authorization", "Bearer <api_key>");
+IRestResponse response = client.Execute(request);
+```
+
+```swift
+import Foundation
+
+let headers = ["Authorization": "Bearer <api_key>"]
+
+let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/inboxes/inbox_id/events")! as URL,
+                                        cachePolicy: .useProtocolCachePolicy,
+                                    timeoutInterval: 10.0)
+request.httpMethod = "GET"
+request.allHTTPHeaderFields = headers
+
+let session = URLSession.shared
+let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
+  if (error != nil) {
+    print(error as Any)
+  } else {
+    let httpResponse = response as? HTTPURLResponse
+    print(httpResponse)
+  }
+})
+
+dataTask.resume()
+```
+
 # List API Keys
 
 GET https://api.agentmail.to/v0/inboxes/{inbox_id}/api-keys
@@ -25747,7 +25959,7 @@ GET https://api.agentmail.to/v0/threads/{thread_id}
 
 **CLI:**
 ```bash
-agentmail threads retrieve --thread-id <thread_id>
+agentmail threads get --thread-id <thread_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/threads/get
@@ -25767,7 +25979,7 @@ paths:
       description: |-
         **CLI:**
         ```bash
-        agentmail threads retrieve --thread-id <thread_id>
+        agentmail threads get --thread-id <thread_id>
         ```
       tags:
         - subpackage_threads
@@ -26310,7 +26522,7 @@ GET https://api.agentmail.to/v0/threads/{thread_id}/attachments/{attachment_id}
 
 **CLI:**
 ```bash
-agentmail threads retrieve-attachment --thread-id <thread_id> --attachment-id <attachment_id>
+agentmail threads get-attachment --thread-id <thread_id> --attachment-id <attachment_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/threads/get-attachment
@@ -26332,8 +26544,8 @@ paths:
 
         ```bash
 
-        agentmail threads retrieve-attachment --thread-id <thread_id>
-        --attachment-id <attachment_id>
+        agentmail threads get-attachment --thread-id <thread_id> --attachment-id
+        <attachment_id>
 
         ```
       tags:
@@ -27573,7 +27785,7 @@ GET https://api.agentmail.to/v0/drafts/{draft_id}
 
 **CLI:**
 ```bash
-agentmail drafts retrieve --draft-id <draft_id>
+agentmail drafts get --draft-id <draft_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/drafts/get
@@ -27593,7 +27805,7 @@ paths:
       description: |-
         **CLI:**
         ```bash
-        agentmail drafts retrieve --draft-id <draft_id>
+        agentmail drafts get --draft-id <draft_id>
         ```
       tags:
         - subpackage_drafts
@@ -28583,7 +28795,7 @@ GET https://api.agentmail.to/v0/webhooks/{webhook_id}
 
 **CLI:**
 ```bash
-agentmail webhooks retrieve --webhook-id <webhook_id>
+agentmail webhooks get --webhook-id <webhook_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/webhooks/get
@@ -28603,7 +28815,7 @@ paths:
       description: |-
         **CLI:**
         ```bash
-        agentmail webhooks retrieve --webhook-id <webhook_id>
+        agentmail webhooks get --webhook-id <webhook_id>
         ```
       tags:
         - subpackage_webhooks
@@ -32383,7 +32595,7 @@ GET https://api.agentmail.to/v0/domains/{domain_id}
 
 **CLI:**
 ```bash
-agentmail domains retrieve --domain-id <domain_id>
+agentmail domains get --domain-id <domain_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/domains/get
@@ -32403,7 +32615,7 @@ paths:
       description: |-
         **CLI:**
         ```bash
-        agentmail domains retrieve --domain-id <domain_id>
+        agentmail domains get --domain-id <domain_id>
         ```
       tags:
         - subpackage_domains
@@ -34378,7 +34590,7 @@ GET https://api.agentmail.to/v0/lists/{direction}/{type}/{entry}
 
 **CLI:**
 ```bash
-agentmail lists retrieve --direction <direction> --type <type> --entry <entry>
+agentmail lists get --direction <direction> --type <type> --entry <entry>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/lists/get
@@ -34400,7 +34612,7 @@ paths:
 
         ```bash
 
-        agentmail lists retrieve --direction <direction> --type <type> --entry
+        agentmail lists get --direction <direction> --type <type> --entry
         <entry>
 
         ```
@@ -36807,7 +37019,7 @@ GET https://api.agentmail.to/v0/pods/{pod_id}
 
 **CLI:**
 ```bash
-agentmail pods retrieve --pod-id <pod_id>
+agentmail pods get --pod-id <pod_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/pods/get
@@ -36827,7 +37039,7 @@ paths:
       description: |-
         **CLI:**
         ```bash
-        agentmail pods retrieve --pod-id <pod_id>
+        agentmail pods get --pod-id <pod_id>
         ```
       tags:
         - subpackage_pods
@@ -37864,7 +38076,7 @@ GET https://api.agentmail.to/v0/pods/{pod_id}/inboxes/{inbox_id}
 
 **CLI:**
 ```bash
-agentmail pods:inboxes retrieve --pod-id <pod_id> --inbox-id <inbox_id>
+agentmail pods:inboxes get --pod-id <pod_id> --inbox-id <inbox_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/pods/inboxes/get
@@ -37884,7 +38096,7 @@ paths:
       description: |-
         **CLI:**
         ```bash
-        agentmail pods:inboxes retrieve --pod-id <pod_id> --inbox-id <inbox_id>
+        agentmail pods:inboxes get --pod-id <pod_id> --inbox-id <inbox_id>
         ```
       tags:
         - subpackage_pods.subpackage_pods/inboxes
@@ -39480,7 +39692,7 @@ GET https://api.agentmail.to/v0/pods/{pod_id}/threads/{thread_id}
 
 **CLI:**
 ```bash
-agentmail pods:threads retrieve --pod-id <pod_id> --thread-id <thread_id>
+agentmail pods:threads get --pod-id <pod_id> --thread-id <thread_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/pods/threads/get
@@ -39497,14 +39709,10 @@ paths:
     get:
       operationId: get
       summary: Get Thread
-      description: >-
+      description: |-
         **CLI:**
-
         ```bash
-
-        agentmail pods:threads retrieve --pod-id <pod_id> --thread-id
-        <thread_id>
-
+        agentmail pods:threads get --pod-id <pod_id> --thread-id <thread_id>
         ```
       tags:
         - subpackage_pods.subpackage_pods/threads
@@ -41361,7 +41569,7 @@ GET https://api.agentmail.to/v0/pods/{pod_id}/drafts/{draft_id}
 
 **CLI:**
 ```bash
-agentmail pods:drafts retrieve --pod-id <pod_id> --draft-id <draft_id>
+agentmail pods:drafts get --pod-id <pod_id> --draft-id <draft_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/pods/drafts/get
@@ -41381,7 +41589,7 @@ paths:
       description: |-
         **CLI:**
         ```bash
-        agentmail pods:drafts retrieve --pod-id <pod_id> --draft-id <draft_id>
+        agentmail pods:drafts get --pod-id <pod_id> --draft-id <draft_id>
         ```
       tags:
         - subpackage_pods.subpackage_pods/drafts
@@ -42391,7 +42599,7 @@ GET https://api.agentmail.to/v0/pods/{pod_id}/domains/{domain_id}
 
 **CLI:**
 ```bash
-agentmail pods:domains retrieve --pod-id <pod_id> --domain-id <domain_id>
+agentmail pods:domains get --pod-id <pod_id> --domain-id <domain_id>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/pods/domains/get
@@ -42408,14 +42616,10 @@ paths:
     get:
       operationId: get
       summary: Get Domain
-      description: >-
+      description: |-
         **CLI:**
-
         ```bash
-
-        agentmail pods:domains retrieve --pod-id <pod_id> --domain-id
-        <domain_id>
-
+        agentmail pods:domains get --pod-id <pod_id> --domain-id <domain_id>
         ```
       tags:
         - subpackage_pods.subpackage_pods/domains
@@ -44463,7 +44667,7 @@ GET https://api.agentmail.to/v0/pods/{pod_id}/lists/{direction}/{type}/{entry}
 
 **CLI:**
 ```bash
-agentmail pods:lists retrieve --pod-id <pod_id> --direction <direction> --type <type> --entry <entry>
+agentmail pods:lists get --pod-id <pod_id> --direction <direction> --type <type> --entry <entry>
 ```
 
 Reference: https://docs.agentmail.to/api-reference/pods/lists/get
@@ -44485,7 +44689,7 @@ paths:
 
         ```bash
 
-        agentmail pods:lists retrieve --pod-id <pod_id> --direction <direction>
+        agentmail pods:lists get --pod-id <pod_id> --direction <direction>
         --type <type> --entry <entry>
 
         ```
@@ -46749,7 +46953,12 @@ dataTask.resume()
 
 GET https://api.agentmail.to/v0/organizations
 
-Get the current organization.
+Returns the organization for the authenticated API key (usage limits, counts, and billing metadata).
+
+**CLI:**
+```bash
+agentmail organizations get
+```
 
 Reference: https://docs.agentmail.to/api-reference/organizations/get
 
@@ -46765,7 +46974,18 @@ paths:
     get:
       operationId: get
       summary: Get Organization
-      description: Get the current organization.
+      description: >-
+        Returns the organization for the authenticated API key (usage limits,
+        counts, and billing metadata).
+
+
+        **CLI:**
+
+        ```bash
+
+        agentmail organizations get
+
+        ```
       tags:
         - subpackage_organizations
       parameters:
@@ -46975,12 +47195,7 @@ let dataTask = session.dataTask(with: request as URLRequest, completionHandler:
 dataTask.resume()
 ```
 
-***
-
-title: Knowledge Base
-subtitle: A collection of answers to frequently asked questions.
-slug: knowledge-base
---------------------
+# Knowledge Base
 
 ## Getting Started
 
@@ -47072,6 +47287,10 @@ slug: knowledge-base
   <Card title="Emails bouncing" icon="fa-solid fa-rotate-left" href="/knowledge-base/emails-bouncing">
     Diagnose and resolve email bounce issues.
   </Card>
+
+  <Card title="Email spoofing protection" icon="fa-solid fa-shield-halved" href="/knowledge-base/inbound-emails-missing">
+    How AgentMail protects your inboxes from unauthenticated senders.
+  </Card>
 </Cards>
 
 ## DNS Guides
@@ -47096,13 +47315,7 @@ Step-by-step instructions for verifying your domain with popular DNS providers.
   </Card>
 </Cards>
 
-
-***
-
-title: What is AgentMail and how is it different?
-subtitle: Understand how AgentMail compares to traditional email providers.
-slug: knowledge-base/what-is-agentmail
---------------------------------------
+# What is AgentMail and how is it different?
 
 AgentMail is email infrastructure built specifically for AI agents. Unlike transactional email APIs that focus on one-way sending, AgentMail is built for two-way agent communication: dedicated inboxes, native threading, and full receiving support with no shared sending domains.
 
@@ -47135,13 +47348,7 @@ AgentMail is the right choice when:
 
 Yes. AgentMail's send API works similarly. Replace your existing send call with `client.inboxes.messages.send()` and you get the same sending capability plus full receiving, threading, and agent identity features on top. See the [Quickstart](/quickstart) to get started in minutes.
 
-
-***
-
-title: What can I do with an AgentMail inbox?
-subtitle: A complete overview of inbox capabilities for AI agents.
-slug: knowledge-base/inbox-capabilities
----------------------------------------
+# What can I do with an AgentMail inbox?
 
 An AgentMail inbox is a full email account for your AI agent. Each inbox gets a unique email address and can send, receive, reply, forward, and manage emails entirely through the API.
 
@@ -47233,13 +47440,7 @@ if threads.threads:
     )
 ```
 
-
-***
-
-title: How do I create my first inbox?
-subtitle: Get up and running with your first AgentMail inbox.
-slug: knowledge-base/creating-first-inbox
------------------------------------------
+# How do I create my first inbox?
 
 Creating an inbox gives your AI agent its own email address. You can create inboxes on the default `@agentmail.to` domain or on your own custom domain.
 
@@ -47332,13 +47533,7 @@ Now that you have an inbox, explore what you can do with it:
 * [Set up webhooks](/webhook-setup) to get notified when emails arrive
 * [Use labels](/labels) to track message state in your agent workflows
 
-
-***
-
-title: How do I get my API key?
-subtitle: Create and manage your AgentMail API keys.
-slug: knowledge-base/getting-api-key
-------------------------------------
+# How do I get my API key?
 
 You need an API key to authenticate requests to the AgentMail API. API keys start with `am_` and are created in the AgentMail Console.
 
@@ -47402,13 +47597,7 @@ No credit card required to get started. The free tier includes:
 
 To create more inboxes or send higher volumes, see the [pricing page](https://agentmail.to/pricing).
 
-
-***
-
-title: How do I handle inbound emails with my agent?
-subtitle: Compare Webhooks and WebSockets for processing incoming emails.
-slug: knowledge-base/handling-inbound-emails
---------------------------------------------
+# How do I handle inbound emails with my agent?
 
 AgentMail offers two ways to process incoming emails, each suited to different use cases.
 
@@ -47512,13 +47701,7 @@ See the [WebSocket Overview](/websockets) for more details.
 
 For most production use cases, **webhooks** are recommended. They are reliable, event-driven, and integrate well with serverless platforms. If you need real-time events without exposing a public URL, **WebSockets** are the best option.
 
-
-***
-
-title: How do I set up allowlists and blocklists?
-subtitle: Control who your AI agent can send to and receive from.
-slug: knowledge-base/allowlists-blocklists
-------------------------------------------
+# How do I set up allowlists and blocklists?
 
 Allowlists and blocklists let you control who your AI agent can communicate with. This is a critical safety feature for autonomous agents running in production with minimal human oversight.
 
@@ -47659,13 +47842,7 @@ Without guardrails, an autonomous agent could email the wrong people, respond to
 
 For more details on the Lists API, see the [Lists core concept](/lists) documentation.
 
-
-***
-
-title: How do I manage threaded conversations?
-subtitle: Maintain context across multi-turn email conversations with your agent.
-slug: knowledge-base/threaded-conversations
--------------------------------------------
+# How do I manage threaded conversations?
 
 Threads are how AgentMail organizes conversations. Every time your agent sends a new email, a thread is created. Replies are automatically grouped into the same thread, giving your agent full conversation context.
 
@@ -47789,13 +47966,7 @@ for thread in unreplied.threads:
 * Use labels like `unreplied`, `replied`, `escalated`, and `resolved` to track conversation state
 * Always reply to the **last message** in a thread to keep email headers correct
 
-
-***
-
-title: How do I build a human-in-the-loop workflow?
-subtitle: Keep humans in control of your agent's email communications.
-slug: knowledge-base/human-in-the-loop
---------------------------------------
+# How do I build a human-in-the-loop workflow?
 
 AgentMail provides several mechanisms for keeping humans involved when agents send emails. You can combine these approaches to match the level of oversight your workflow requires.
 
@@ -47895,13 +48066,7 @@ This acts as a hard safety boundary. Your agent can only email recipients you ha
 * **Use labels consistently** across your agents so dashboards and alerting work reliably
 * **Combine approaches:** for example, use allowlists for autonomous sending to known recipients, drafts for unknown recipients, and CC a human on everything during the first week
 
-
-***
-
-title: How do I use Pods for multi-tenant email?
-subtitle: 'Isolate inboxes, domains, and data across tenants with Pods.'
-slug: knowledge-base/pods-multi-tenant
---------------------------------------
+# How do I use Pods for multi-tenant email?
 
 Pods provide tenant isolation for multi-tenant applications. Each Pod is an isolated workspace containing its own inboxes, domains, threads, and drafts, completely separated from other Pods.
 
@@ -48015,13 +48180,7 @@ client.pods.delete(pod_id=pod.pod_id)
 
 For more details, see the [Pods core concept](/pods) documentation.
 
-
-***
-
-title: How do I use labels to track email state?
-subtitle: Use labels to manage agent workflow state on emails and threads.
-slug: knowledge-base/labels-track-state
----------------------------------------
+# How do I use labels to track email state?
 
 Labels are string-based tags you attach to messages and threads. They are the primary way agents track state, classify emails, and filter conversations in AgentMail.
 
@@ -48149,13 +48308,7 @@ for thread_item in unreplied.threads:
 
 For more details, see the [Labels core concept](/labels) documentation.
 
-
-***
-
-title: How do I set up a custom domain?
-subtitle: Send emails from your own domain instead of @agentmail.to.
-slug: knowledge-base/custom-domain-setup
-----------------------------------------
+# How do I set up a custom domain?
 
 Custom domains let your agent send emails from your brand (e.g., `agent@yourcompany.com`) instead of the default `@agentmail.to`. This improves deliverability and builds trust with recipients.
 
@@ -48247,13 +48400,7 @@ console.log(`Created: ${inbox.inboxId}`);
 * **One SPF record per domain:** if you already have an SPF record, merge AgentMail's `include:` into the existing record rather than creating a second one
   For a detailed walkthrough, see the [Creating Custom Domains](/custom-domains) guide.
 
-
-***
-
-title: 'How do I set up SPF, DKIM, and DMARC?'
-subtitle: Authenticate your domain for reliable email deliverability.
-slug: knowledge-base/spf-dkim-dmarc
------------------------------------
+# How do I set up SPF, DKIM, and DMARC?
 
 SPF, DKIM, and DMARC are three email authentication protocols that prove your emails are legitimate. They are essential for deliverability: Gmail, Outlook, and other major providers now require all three for reliable inbox placement.
 
@@ -48344,13 +48491,7 @@ For step-by-step DNS instructions, see our provider guides: [Cloudflare](/knowle
 
 For a deeper explanation of how these protocols work, see the [SPF, DKIM, DMARC](/email-protocols) documentation.
 
-
-***
-
-title: Why are my emails going to spam?
-subtitle: Troubleshoot and fix spam folder placement issues.
-slug: knowledge-base/emails-going-to-spam
------------------------------------------
+# Why are my emails going to spam?
 
 If your agent's emails are landing in spam instead of the inbox, work through these common causes in order. The most frequent issues are at the top.
 
@@ -48415,13 +48556,7 @@ If you have checked all of the above and emails are still going to spam, reach o
 
 For a comprehensive guide to maximizing deliverability, see the [Email Deliverability](/email-deliverability) best practices.
 
-
-***
-
-title: Warming Up
-subtitle: Gradually build sending reputation on a new domain or inbox.
-slug: knowledge-base/domain-warming
------------------------------------
+# Warming Up
 
 Warming up is the process of gradually increasing your email volume on a new domain to build sender reputation with mailbox providers like Gmail, Outlook, and Yahoo.
 You can connect AgentMail inboxes to Instantly and Smartlead for programmatic warm up using [SMTP credentials](https://docs.agentmail.to/imap-smtp#finding-your-credentials).
@@ -48496,13 +48631,7 @@ You can track bounces and complaints by using [Query Metrics](https://docs.agent
 
 For more deliverability best practices, see the [Email Deliverability](/email-deliverability) guide.
 
-
-***
-
-title: How do I avoid MX record conflicts?
-subtitle: Add AgentMail DNS records without breaking existing email.
-slug: knowledge-base/mx-record-conflicts
-----------------------------------------
+# How do I avoid MX record conflicts?
 
 If you already use Gmail, Outlook, or another email provider for your domain, adding AgentMail's MX records could conflict with your existing setup. Here is how to avoid that.
 
@@ -48579,13 +48708,7 @@ Your team's email continues to flow through Gmail. Agent emails go through Agent
 
 Pick whatever makes sense for your brand. The important thing is that it is a separate subdomain from your root domain's email.
 
-
-***
-
-title: What does a 403 error mean?
-subtitle: Common causes of API 403 Forbidden errors and how to fix them.
-slug: knowledge-base/api-403-error
-----------------------------------
+# What does a 403 error mean?
 
 A `403 Forbidden` response from the AgentMail API means your request was rejected. This can happen for several reasons, and the fix depends on the cause.
 
@@ -48647,13 +48770,7 @@ If you get a `200` response, your key is valid and working. You can then copy th
 
 If none of the above resolves your issue, reach out in our [Discord](https://discord.com/invite/hTYatWYWBc) support channel or email [support@agentmail.cc](mailto:support@agentmail.cc) with the full error response and the endpoint you are calling.
 
-
-***
-
-title: What are the rate limits?
-subtitle: Understand AgentMail's rate limits and how to work within them.
-slug: knowledge-base/rate-limits
---------------------------------
+# What are the rate limits?
 
 AgentMail is built for high-volume agent workflows. Limits vary by plan.
 
@@ -48707,13 +48824,7 @@ async function sendWithRetry(inboxId: string, params: any, maxRetries = 3) {
 
 If you need higher sending volumes or more inboxes than your current plan allows, contact [support@agentmail.cc](mailto:support@agentmail.cc) or visit the [pricing page](https://agentmail.to/pricing) for enterprise options.
 
-
-***
-
-title: How do I prevent duplicate sends?
-subtitle: Use idempotency to avoid sending the same email twice.
-slug: knowledge-base/preventing-duplicate-sends
------------------------------------------------
+# How do I prevent duplicate sends?
 
 AI agents can sometimes retry requests due to network errors, timeouts, or logic bugs. Without safeguards, this can cause the same email to be sent multiple times. Here is how to prevent that.
 
@@ -48802,13 +48913,7 @@ Since drafts support `clientId`, creating the same draft multiple times is safe.
 
 For more details, see the [Idempotent Requests](/idempotency) guide.
 
-
-***
-
-title: Why is my domain not verifying?
-subtitle: What to do when your domain verification is stuck.
-slug: knowledge-base/domain-not-verifying
------------------------------------------
+# Why is my domain not verifying?
 
 If your domain is stuck in a pending or failed verification state, work through these common causes.
 
@@ -48880,13 +48985,7 @@ You can check your domain's status in the [AgentMail Console](https://console.ag
 
 If you have checked all of the above and your domain is still not verifying, email [support@agentmail.cc](mailto:support@agentmail.cc) with your domain name and a screenshot of your DNS records. We can help diagnose the issue.
 
-
-***
-
-title: Why are my emails bouncing?
-subtitle: Diagnose and resolve email bounce issues.
-slug: knowledge-base/emails-bouncing
-------------------------------------
+# Why are my emails bouncing?
 
 A bounced email means the recipient's mail server rejected your message. Understanding the bounce type helps you take the right action.
 
@@ -48971,13 +49070,93 @@ await client.webhooks.create({
 
 For more on maintaining healthy sending metrics, see the [Email Deliverability](/email-deliverability) best practices.
 
+# Why are my emails not showing up?
 
-***
+<Warning>
+  **The sender's domain must have SPF or DKIM configured.** To reduce spoofing and phishing, AgentMail now drops inbound emails when the sender's domain has neither SPF nor DKIM set up. If a sender reports that their email never arrived, this is the most likely cause — once they configure SPF/DKIM on their domain, their emails will start landing in your inbox again.
+</Warning>
+
+AgentMail verifies every inbound email using SPF, DKIM, and DMARC authentication before delivering it to your inbox. Emails that fail any of these checks are dropped to prevent spoofing, phishing, and spam from reaching your agents.
+
+This is the same standard enforced by Gmail, Outlook, Yahoo, and other major email providers.
+
+## How inbound authentication works
+
+When an email arrives, AgentMail inspects the SPF, DKIM, and DMARC verdicts provided by the receiving mail server. To be delivered, an email must meet **all** of the following conditions:
+
+* Neither SPF nor DKIM returns a `FAIL` verdict
+* At least one of SPF or DKIM is configured (not both `GRAY`)
+* DMARC does not return `FAIL` (unless the sender's DMARC policy is `none`)
+* The message passes virus scanning
+
+If any check fails, the email is dropped.
+
+| Scenario                       | SPF  | DKIM | Result    |
+| ------------------------------ | ---- | ---- | --------- |
+| Both pass                      | PASS | PASS | Delivered |
+| One passes, other unconfigured | PASS | GRAY | Delivered |
+| One passes, other unconfigured | GRAY | PASS | Delivered |
+| Neither configured             | GRAY | GRAY | Dropped   |
+| Either explicitly fails        | FAIL | any  | Dropped   |
+| Either explicitly fails        | any  | FAIL | Dropped   |
+
+<Warning>
+  Emails dropped due to failed authentication are **silently rejected**. The sender's mail server may still report successful delivery because AgentMail's servers did receive the message, but it was rejected during authentication verification. The sender gets no bounce-back or error notification.
+</Warning>
+
+## Why this matters
+
+Without these checks, anyone could send emails claiming to be from any domain. SPF and DKIM authentication proves that the sending server is authorized to send on behalf of the domain in the `From` address, while DMARC ties those results to the domain's published policy. Dropping unauthenticated emails protects your agents from:
+
+* **Spoofing:** forged sender addresses impersonating trusted contacts
+* **Phishing:** malicious emails designed to trick your agent into taking harmful actions
+* **Spam:** bulk unsolicited email from unverified sources
 
-title: 'DNS Guide: Cloudflare'
-subtitle: Step-by-step instructions for adding AgentMail DNS records in Cloudflare.
-slug: knowledge-base/dns-cloudflare
------------------------------------
+## Diagnosing missing emails
+
+If a sender reports that their email never arrived, check whether their domain has SPF and DKIM records configured:
+
+```bash
+# check for SPF record
+dig TXT example.com +short
+# look for a record starting with "v=spf1"
+```
+
+For DKIM, use [MXToolbox DKIM Lookup](https://mxtoolbox.com/dkim.aspx) or a similar tool. DKIM records are stored under a selector-specific subdomain (e.g., `google._domainkey.example.com`), and the selector name varies by email provider, so there is no single DNS query that covers all cases.
+
+You can also use [MXToolbox SPF Lookup](https://mxtoolbox.com/spf.aspx) to verify SPF records online.
+
+If the domain has neither an SPF record nor a DKIM record, that is the cause. Emails from that domain will be dropped by AgentMail and likely by other providers as well.
+
+## What to tell the sender
+
+The sender needs to configure SPF and/or DKIM on their domain's DNS. This is not something you can fix on the AgentMail side, as the records must be set up by the domain owner.
+
+* Add an SPF record to authorize their mail server (e.g., `v=spf1 include:_spf.google.com ~all` for Google Workspace)
+* Enable DKIM signing through their email provider's admin console
+* Consider adding a DMARC record for full authentication coverage
+
+Most email providers have setup guides: [Google Workspace](https://support.google.com/a/answer/33786), [Microsoft 365](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/email-authentication-spf-configure), [Amazon SES](https://docs.aws.amazon.com/ses/latest/dg/send-email-authentication-spf.html).
+
+## Google Workspace and internal routing
+
+If the sender uses Google Workspace and the AgentMail inbox is on a subdomain of a Google Workspace domain, Google may route the email internally instead of sending it through external MX records. In this case, the email never reaches AgentMail's servers at all.
+
+For example, if the Google Workspace domain is `yourcompany.com` and the AgentMail inbox is on `agents.yourcompany.com`, Google Workspace may intercept emails to `agents.yourcompany.com` and deliver them internally.
+
+**How to fix:** In Google Admin Console, go to **Apps > Google Workspace > Gmail > Routing** and add a routing rule that sends mail for the AgentMail subdomain to the external MX records instead of handling it internally.
+
+## Still not receiving emails?
+
+If the sender's domain does have SPF/DKIM configured and emails are still not arriving:
+
+* Verify your domain's MX records are correctly pointing to AgentMail (see [MX record conflicts](/knowledge-base/mx-record-conflicts))
+* Check that your domain is fully verified in the [AgentMail Console](https://console.agentmail.to)
+* Make sure you are listening for incoming emails via [webhooks or WebSockets](/knowledge-base/handling-inbound-emails)
+
+If none of the above resolves the issue, reach out in our [Discord](https://discord.com/invite/hTYatWYWBc) support channel or email [support@agentmail.cc](mailto:support@agentmail.cc).
+
+# DNS Guide: Cloudflare
 
 ## Steps
 
@@ -49045,13 +49224,7 @@ Cloudflare DNS typically propagates within **1 to 5 minutes**, making it one of
 
 * **Name field auto-strips domain:** Cloudflare removes the domain portion from the Name field automatically. If your DKIM selector is `agentmail._domainkey`, enter just that. Do not enter `agentmail._domainkey.yourdomain.com`, or the record will be created incorrectly.
 
-
-***
-
-title: 'DNS Guide: GoDaddy'
-subtitle: Step-by-step instructions for adding AgentMail DNS records in GoDaddy.
-slug: knowledge-base/dns-godaddy
---------------------------------
+# DNS Guide: GoDaddy
 
 ## Steps
 
@@ -49116,13 +49289,7 @@ GoDaddy DNS typically propagates within **15 to 30 minutes**, but it can occasio
 
 * **Parked domain or forwarding:** If your domain is parked or has forwarding enabled, GoDaddy may override your MX records. Disable parking and forwarding before setting up email receiving.
 
-
-***
-
-title: 'DNS Guide: Route 53 (AWS)'
-subtitle: Step-by-step instructions for adding AgentMail DNS records in AWS Route 53.
-slug: knowledge-base/dns-route53
---------------------------------
+# DNS Guide: Route 53 (AWS)
 
 ## Steps
 
@@ -49190,13 +49357,25 @@ Route 53 name servers typically pick up changes within **60 seconds**, but full
 
 * **Multiple values in one record:** Route 53 lets you add multiple values to a single record. If you need to add a second MX entry, add it as a new line in the same MX record rather than creating a separate record.
 
+* **DKIM TXT record too long (CharacterStringTooLong error):** If your DKIM record is provided as a TXT value (rather than a CNAME), the DKIM public key is often longer than the 255-character limit that Route 53 enforces per string segment. You will see an error like `CharacterStringTooLong (Value is too long)`. To fix this, split the value into two quoted strings within a single record. The split point should be near the middle of the `p=` value. The two quoted strings must have **no space and no line break** between the closing and opening quotes. For example:
 
-***
+  ```
+  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhki...firsthalf""secondhalf...wIDAQAB"
+  ```
+
+  In Route 53, paste the entire value (both quoted strings) into the **Value** field as a single entry. If Route 53 shows two separate copy-pastable values instead of one, there is likely a space or line break between the two strings. Remove it so the closing `"` and opening `"` are directly adjacent (`""`).
+
+  **Incorrect:** A space or line break between the two quoted strings causes Route 53 to treat them as separate values.
+
+  <img src="https://files.buildwithfern.com/https://agentmail-production.docs.buildwithfern.com/5145d22514b03251934e96ef49b78f8ca79e6b20bfa7ec5065a343ac547338e9/assets/route53-dkim-incorrect.png" alt="Incorrect Route 53 DKIM configuration with space between quoted strings" />
 
-title: 'DNS Guide: Namecheap'
-subtitle: Step-by-step instructions for adding AgentMail DNS records in Namecheap.
-slug: knowledge-base/dns-namecheap
-----------------------------------
+  **Correct:** The two quoted strings are directly adjacent with no space, producing a single value in Route 53.
+
+  <img src="https://files.buildwithfern.com/https://agentmail-production.docs.buildwithfern.com/d67b72b3e23c286ef81bb101c57098bab684785fca4bf3791fd7f0fffe864740/assets/route53-dkim-correct.png" alt="Correct Route 53 DKIM configuration with no space between quoted strings" />
+
+  You can also use the AWS CLI to add the record, which handles multi-string TXT values more reliably.
+
+# DNS Guide: Namecheap
 
 ## Steps
 
@@ -49263,4 +49442,3 @@ Namecheap DNS typically propagates within **15 to 30 minutes**, but in some case
 
 * **Propagation delays:** Unlike some providers, Namecheap propagation can take 15 to 30 minutes. If verification fails, wait and retry before troubleshooting further.
 
-