agentmail 0.4.11 → 0.4.13

package/dist/llms-full.txt

@@ -581,6 +581,34 @@ Here at AgentMail we've now made an `Inbox` an API resource, meaning you can per
   domains](/guides/domains/managing-domains) to learn more.
 </Tip>
 
+## Inbox-scoped API keys
+
+You can create API keys that are restricted to a single inbox. An inbox-scoped key can only access that inbox's threads, messages, and drafts. This is useful when you want to give an agent or integration the minimum access it needs.
+
+<CodeBlocks>
+  ```python
+  # Create a key scoped to one inbox
+  key = client.inboxes.api_keys.create(
+      new_inbox.inbox_id,
+      name="support-agent-key"
+  )
+
+  # The full key is only returned once
+  print(key.api_key)
+  ```
+
+  ```typescript title="TypeScript"
+  const key = await client.inboxes.apiKeys.create(newInbox.id, {
+    name: "support-agent-key",
+  });
+
+  // The full key is only returned once
+  console.log(key.apiKey);
+  ```
+</CodeBlocks>
+
+See the [Multi-Tenancy guide](/multi-tenancy#inbox-scoped-keys) for more on scoped keys.
+
 ## Copy for Cursor / Claude
 
 Copy one of the blocks below into Cursor or Claude for complete Inboxes API knowledge in one shot.
@@ -598,6 +626,9 @@ Copy one of the blocks below into Cursor or Claude for complete Inboxes API know
   - inboxes.list(limit?, page_token?)
   - inboxes.update(inbox_id, display_name)
   - inboxes.delete(inbox_id)
+  - inboxes.api_keys.create(inbox_id, name) — inbox-scoped key
+  - inboxes.api_keys.list(inbox_id)
+  - inboxes.api_keys.delete(inbox_id, api_key_id)
 
   Errors: SDK raises on 4xx/5xx. Rate limit: 429 with Retry-After.
   """
@@ -629,6 +660,9 @@ Copy one of the blocks below into Cursor or Claude for complete Inboxes API know
    * - inboxes.list({ limit?, pageToken? })
    * - inboxes.update(inboxId, { displayName })
    * - inboxes.delete(inboxId)
+   * - inboxes.apiKeys.create(inboxId, { name }) — inbox-scoped key
+   * - inboxes.apiKeys.list(inboxId)
+   * - inboxes.apiKeys.delete(inboxId, apiKeyId)
    *
    * Errors: SDK throws on 4xx/5xx. Rate limit: 429 with Retry-After.
    */
@@ -2696,7 +2730,7 @@ async function offboardCustomer(podId: string) {
 
 **What's NOT Isolated to a Pod:**
 
-* Organization-level API keys (these can access any resources in any pod). Use [scoped API keys](/multi-tenancy#step-3-create-scoped-api-keys) to restrict access to a single pod.
+* Organization-level API keys (these can access any resources in any pod). Use [pod-scoped API keys](/multi-tenancy#pod-scoped-keys) to restrict access to a single pod, or [inbox-scoped API keys](/multi-tenancy#inbox-scoped-keys) to restrict access to a single inbox.
 
 ## Common Patterns and Use Cases
 
@@ -2783,9 +2817,9 @@ Pod: "Marketing-Agent"
 </Accordion>
 
 <Accordion title="Can I set custom permissions per pod?">
-  Yes! You can create scoped API keys that are restricted to a single pod. A
-  scoped key can only access resources within its pod. See the
-  [Multi-Tenancy guide](/multi-tenancy) for details on provisioning scoped keys.
+  Yes! You can create pod-scoped API keys that are restricted to a single pod, or
+  inbox-scoped API keys that are restricted to a single inbox within a pod. See the
+  [Multi-Tenancy guide](/multi-tenancy#scoped-api-keys) for details on provisioning scoped keys.
 </Accordion>
 
 ## Next Steps
@@ -2794,6 +2828,379 @@ Pod: "Marketing-Agent"
 * Explore [Domains](/custom-domains) to set up custom email domains for your pods
 
 
+***
+
+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.
+-------------------------------------
+
+## What are Permissions?
+
+`Permissions` let you restrict what an API key can do. By default, an API key has full access within its scope (organization, pod, or inbox). When you provide a `permissions` object, it acts as a **whitelist**: only the permissions you explicitly set to `true` are granted. Everything else is denied.
+
+This gives you fine-grained control over which resources and operations each key can access, on top of the existing scope-based isolation provided by [pod-scoped](/pods) and [inbox-scoped](/inboxes#inbox-scoped-api-keys) keys.
+
+## How Permissions Work
+
+### Whitelist model
+
+When you create an API key with a `permissions` object, it switches from "full access" mode to "whitelist" mode:
+
+* **No `permissions` field**: The key has full access within its scope. This is the default and is backward compatible with existing keys.
+* **`permissions` present**: Only permissions set to `true` are allowed. Any permission that is omitted or set to `false` is denied.
+
+<Callout intent="info" title="Backward compatibility">
+  Existing API keys without a `permissions` field continue to work exactly as before with full access. The whitelist only activates when you explicitly provide the `permissions` object.
+</Callout>
+
+### Intersection with scope
+
+Permissions are intersected with the key's scope. A key scoped to a single inbox cannot gain organization-level capabilities (like `inbox_create` or `domain_create`) even if those permissions are set to `true`. The effective permissions are always the intersection of what the scope allows and what the `permissions` object grants.
+
+### Privilege escalation protection
+
+A restricted API key cannot create a child key with more permissions than itself. When creating a new key, the child's permissions are automatically constrained to the parent's effective permissions. This prevents privilege escalation through key creation.
+
+## Permissions Reference
+
+### Inboxes
+
+| Permission     | Description           |
+| -------------- | --------------------- |
+| `inbox_read`   | Read inbox details    |
+| `inbox_create` | Create new inboxes    |
+| `inbox_update` | Update inbox settings |
+| `inbox_delete` | Delete inboxes        |
+
+### Threads
+
+| Permission      | Description    |
+| --------------- | -------------- |
+| `thread_read`   | Read threads   |
+| `thread_delete` | Delete threads |
+
+### Messages
+
+| Permission       | Description           |
+| ---------------- | --------------------- |
+| `message_read`   | Read messages         |
+| `message_send`   | Send messages         |
+| `message_update` | Update message labels |
+
+### Label Visibility
+
+| Permission           | Description                        |
+| -------------------- | ---------------------------------- |
+| `label_spam_read`    | Access messages labeled as spam    |
+| `label_blocked_read` | Access messages labeled as blocked |
+| `label_trash_read`   | Access messages labeled as trash   |
+
+<Info>
+  When a label visibility permission is denied, items with that label are automatically excluded from list results and return "not found" on direct access. For example, setting `label_spam_read` to `false` means the key will never see spam messages in any listing or lookup.
+</Info>
+
+### Drafts
+
+| Permission     | Description   |
+| -------------- | ------------- |
+| `draft_read`   | Read drafts   |
+| `draft_create` | Create drafts |
+| `draft_update` | Update drafts |
+| `draft_delete` | Delete drafts |
+| `draft_send`   | Send drafts   |
+
+### Webhooks
+
+| Permission       | Description                 |
+| ---------------- | --------------------------- |
+| `webhook_read`   | Read webhook configurations |
+| `webhook_create` | Create webhooks             |
+| `webhook_update` | Update webhooks             |
+| `webhook_delete` | Delete webhooks             |
+
+### Domains
+
+| Permission      | Description         |
+| --------------- | ------------------- |
+| `domain_read`   | Read domain details |
+| `domain_create` | Create domains      |
+| `domain_update` | Update domains      |
+| `domain_delete` | Delete domains      |
+
+### Lists
+
+| Permission          | Description         |
+| ------------------- | ------------------- |
+| `list_entry_read`   | Read list entries   |
+| `list_entry_create` | Create list entries |
+| `list_entry_delete` | Delete list entries |
+
+### Metrics
+
+| Permission     | Description  |
+| -------------- | ------------ |
+| `metrics_read` | Read metrics |
+
+### API Keys
+
+| Permission       | Description     |
+| ---------------- | --------------- |
+| `api_key_read`   | Read API keys   |
+| `api_key_create` | Create API keys |
+| `api_key_delete` | Delete API keys |
+
+### Pods
+
+| Permission   | Description |
+| ------------ | ----------- |
+| `pod_read`   | Read pods   |
+| `pod_create` | Create pods |
+| `pod_delete` | Delete pods |
+
+## Code Examples
+
+### Read-only key
+
+Create an API key that can read all resources but cannot create, update, or delete anything.
+
+<CodeBlocks>
+  ```python title="Python"
+  from agentmail import AgentMail
+
+  client = AgentMail(api_key="YOUR_API_KEY")
+
+  key = client.api_keys.create(
+      name="read-only-agent",
+      permissions={
+          "inbox_read": True,
+          "thread_read": True,
+          "message_read": True,
+          "draft_read": True,
+          "webhook_read": True,
+          "domain_read": True,
+          "list_entry_read": True,
+          "metrics_read": True,
+          "api_key_read": True,
+          "pod_read": True,
+          "label_spam_read": True,
+          "label_blocked_read": True,
+          "label_trash_read": True,
+      }
+  )
+
+  print(key.api_key)
+  ```
+
+  ```typescript title="TypeScript"
+  import { AgentMailClient } from "agentmail";
+
+  const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });
+
+  const key = await client.apiKeys.create({
+    name: "read-only-agent",
+    permissions: {
+      inboxRead: true,
+      threadRead: true,
+      messageRead: true,
+      draftRead: true,
+      webhookRead: true,
+      domainRead: true,
+      listEntryRead: true,
+      metricsRead: true,
+      apiKeyRead: true,
+      podRead: true,
+      labelSpamRead: true,
+      labelBlockedRead: true,
+      labelTrashRead: true,
+    },
+  });
+
+  console.log(key.apiKey);
+  ```
+</CodeBlocks>
+
+### No-spam key
+
+Create a key with full access but block visibility into spam, blocked, and trash content. This is useful for agent-facing keys where you want to prevent the agent from processing unwanted email.
+
+<CodeBlocks>
+  ```python title="Python"
+  key = client.api_keys.create(
+      name="clean-inbox-agent",
+      permissions={
+          "inbox_read": True,
+          "inbox_create": True,
+          "inbox_update": True,
+          "inbox_delete": True,
+          "thread_read": True,
+          "thread_delete": True,
+          "message_read": True,
+          "message_send": True,
+          "message_update": True,
+          "label_spam_read": False,
+          "label_blocked_read": False,
+          "label_trash_read": False,
+          "draft_read": True,
+          "draft_create": True,
+          "draft_update": True,
+          "draft_delete": True,
+          "draft_send": True,
+          "webhook_read": True,
+          "webhook_create": True,
+          "webhook_update": True,
+          "webhook_delete": True,
+          "domain_read": True,
+          "domain_create": True,
+          "domain_update": True,
+          "domain_delete": True,
+          "list_entry_read": True,
+          "list_entry_create": True,
+          "list_entry_delete": True,
+          "metrics_read": True,
+          "api_key_read": True,
+          "api_key_create": True,
+          "api_key_delete": True,
+          "pod_read": True,
+          "pod_create": True,
+          "pod_delete": True,
+      }
+  )
+  ```
+
+  ```typescript title="TypeScript"
+  const key = await client.apiKeys.create({
+    name: "clean-inbox-agent",
+    permissions: {
+      inboxRead: true,
+      inboxCreate: true,
+      inboxUpdate: true,
+      inboxDelete: true,
+      threadRead: true,
+      threadDelete: true,
+      messageRead: true,
+      messageSend: true,
+      messageUpdate: true,
+      labelSpamRead: false,
+      labelBlockedRead: false,
+      labelTrashRead: false,
+      draftRead: true,
+      draftCreate: true,
+      draftUpdate: true,
+      draftDelete: true,
+      draftSend: true,
+      webhookRead: true,
+      webhookCreate: true,
+      webhookUpdate: true,
+      webhookDelete: true,
+      domainRead: true,
+      domainCreate: true,
+      domainUpdate: true,
+      domainDelete: true,
+      listEntryRead: true,
+      listEntryCreate: true,
+      listEntryDelete: true,
+      metricsRead: true,
+      apiKeyRead: true,
+      apiKeyCreate: true,
+      apiKeyDelete: true,
+      podRead: true,
+      podCreate: true,
+      podDelete: true,
+    },
+  });
+  ```
+</CodeBlocks>
+
+## Copy for Cursor / Claude
+
+Copy one of the blocks below into Cursor or Claude for complete Permissions API knowledge in one shot.
+
+<CodeBlocks>
+  ```python title="Python"
+  """
+  AgentMail Permissions — copy into Cursor/Claude.
+
+  Permissions are a whitelist on API keys. No `permissions` field = full access.
+  When `permissions` is set, only `True` values are granted; omitted or `False` = denied.
+  Permissions intersect with scope (pod/inbox). A restricted key cannot create a more privileged child key.
+
+  Permission fields (all optional<bool>, resource_action format):
+    Inboxes: inbox_read, inbox_create, inbox_update, inbox_delete
+    Threads: thread_read, thread_delete
+    Messages: message_read, message_send, message_update
+    Label visibility: label_spam_read, label_blocked_read, label_trash_read
+    Drafts: draft_read, draft_create, draft_update, draft_delete, draft_send
+    Webhooks: webhook_read, webhook_create, webhook_update, webhook_delete
+    Domains: domain_read, domain_create, domain_update, domain_delete
+    Lists: list_entry_read, list_entry_create, list_entry_delete
+    Metrics: metrics_read
+    API Keys: api_key_read, api_key_create, api_key_delete
+    Pods: pod_read, pod_create, pod_delete
+
+  API: api_keys.create(name, permissions={...})
+  """
+  from agentmail import AgentMail
+
+  client = AgentMail(api_key="YOUR_API_KEY")
+
+  # read-only key
+  key = client.api_keys.create(
+      name="read-only",
+      permissions={"inbox_read": True, "message_read": True, "thread_read": True}
+  )
+  print(key.api_key)
+  ```
+
+  ```typescript title="TypeScript"
+  /**
+   * AgentMail Permissions — copy into Cursor/Claude.
+   *
+   * Permissions are a whitelist on API keys. No `permissions` field = full access.
+   * When `permissions` is set, only `true` values are granted; omitted or `false` = denied.
+   * Permissions intersect with scope (pod/inbox). A restricted key cannot create a more privileged child key.
+   *
+   * Permission fields (all optional boolean, resourceAction format):
+   *   Inboxes: inboxRead, inboxCreate, inboxUpdate, inboxDelete
+   *   Threads: threadRead, threadDelete
+   *   Messages: messageRead, messageSend, messageUpdate
+   *   Label visibility: labelSpamRead, labelBlockedRead, labelTrashRead
+   *   Drafts: draftRead, draftCreate, draftUpdate, draftDelete, draftSend
+   *   Webhooks: webhookRead, webhookCreate, webhookUpdate, webhookDelete
+   *   Domains: domainRead, domainCreate, domainUpdate, domainDelete
+   *   Lists: listEntryRead, listEntryCreate, listEntryDelete
+   *   Metrics: metricsRead
+   *   API Keys: apiKeyRead, apiKeyCreate, apiKeyDelete
+   *   Pods: podRead, podCreate, podDelete
+   *
+   * API: apiKeys.create({ name, permissions: {...} })
+   */
+  import { AgentMailClient } from "agentmail";
+
+  const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });
+
+  async function main() {
+    // read-only key
+    const key = await client.apiKeys.create({
+      name: "read-only",
+      permissions: { inboxRead: true, messageRead: true, threadRead: true },
+    });
+    console.log(key.apiKey);
+  }
+  main();
+  ```
+</CodeBlocks>
+
+## Best Practices
+
+* **Use the principle of least privilege.** Only grant the permissions your agent actually needs. A support agent that reads and replies to emails does not need `domain_create` or `inbox_delete`.
+* **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.
+
+
 ***
 
 title: Agent Onboarding
@@ -3369,6 +3776,124 @@ 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.
 
 
+***
+
+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
+-----------------------------------------------------------------------
+
+## Getting started
+
+[Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) is an open-source framework for building AI agents. By connecting AgentMail to your ADK agent via the [AgentMail MCP server](https://github.com/agentmail-to/agentmail-smithery-mcp), your agent can create inboxes, send and receive emails, manage threads, and handle attachments using natural language.
+
+## Use cases
+
+* **Give agents their own inboxes:** Create dedicated email addresses for your agents so they can send and receive emails independently, just like a human team member.
+* **Automate email workflows:** Let your agent handle email conversations end to end, including sending initial outreach, reading replies, and following up on threads.
+* **Manage conversations across inboxes:** List and search across threads and messages, forward emails, and retrieve attachments to keep your agent informed and responsive.
+
+## Prerequisites
+
+1. An [AgentMail account](https://agentmail.to/) with an API key from the [AgentMail Console](https://console.agentmail.to)
+2. [Google ADK](https://google.github.io/adk-docs/get-started/) installed (`pip install google-adk` or `npm install @google/adk`)
+
+## Setup
+
+ADK supports AgentMail through the MCP tool interface. Connect the AgentMail MCP server as a local stdio transport:
+
+<CodeBlocks>
+  ```python title="Python"
+  from google.adk.agents import Agent
+  from google.adk.tools.mcp_tool import McpToolset
+  from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
+  from mcp import StdioServerParameters
+
+  AGENTMAIL_API_KEY = "YOUR_AGENTMAIL_API_KEY"
+
+  root_agent = Agent(
+      model="gemini-2.5-pro",
+      name="agentmail_agent",
+      instruction="Help users manage email inboxes and send messages",
+      tools=[
+          McpToolset(
+              connection_params=StdioConnectionParams(
+                  server_params=StdioServerParameters(
+                      command="npx",
+                      args=[
+                          "-y",
+                          "agentmail-mcp",
+                      ],
+                      env={
+                          "AGENTMAIL_API_KEY": AGENTMAIL_API_KEY,
+                      }
+                  ),
+                  timeout=30,
+              ),
+          )
+      ],
+  )
+  ```
+
+  ```typescript title="TypeScript"
+  import { LlmAgent, MCPToolset } from "@google/adk";
+
+  const AGENTMAIL_API_KEY = "YOUR_AGENTMAIL_API_KEY";
+
+  const rootAgent = new LlmAgent({
+      model: "gemini-2.5-pro",
+      name: "agentmail_agent",
+      instruction: "Help users manage email inboxes and send messages",
+      tools: [
+          new MCPToolset({
+              type: "StdioConnectionParams",
+              serverParams: {
+                  command: "npx",
+                  args: ["-y", "agentmail-mcp"],
+                  env: {
+                      AGENTMAIL_API_KEY: AGENTMAIL_API_KEY,
+                  },
+              },
+          }),
+      ],
+  });
+
+  export { rootAgent };
+  ```
+</CodeBlocks>
+
+## Available tools
+
+Once connected, your ADK agent has access to the following AgentMail tools:
+
+### Inbox management
+
+| Tool           | Description                                   |
+| -------------- | --------------------------------------------- |
+| `list_inboxes` | List all inboxes                              |
+| `get_inbox`    | Get details for a specific inbox              |
+| `create_inbox` | Create a new inbox with a username and domain |
+| `delete_inbox` | Delete an inbox                               |
+
+### Thread management
+
+| Tool             | Description                             |
+| ---------------- | --------------------------------------- |
+| `list_threads`   | List threads in an inbox                |
+| `get_thread`     | Get a specific thread with its messages |
+| `get_attachment` | Download an attachment from a message   |
+
+### Message operations
+
+| Tool               | Description                                   |
+| ------------------ | --------------------------------------------- |
+| `send_message`     | Send a new email from an inbox                |
+| `reply_to_message` | Reply to an existing message                  |
+| `forward_message`  | Forward a message to another recipient        |
+| `update_message`   | Update message properties such as read status |
+
+
 ***
 
 title: OpenClaw
@@ -4701,10 +5226,14 @@ Then provision their resources:
 
 ## Scoped API Keys
 
-By default, API keys are organization-level and can access everything across all pods. Scoped API keys are restricted to a single pod. If a key is scoped to Acme's pod, it can only touch Acme's resources. Nothing else.
+By default, API keys are organization-level and can access everything across all pods. Scoped API keys restrict access to a single pod or a single inbox. If a key is scoped to Acme's pod, it can only touch Acme's resources. Nothing else.
 
 This is useful when you want to hand a key to a tenant's service or agent without exposing your whole org.
 
+### Pod-scoped keys
+
+Pod-scoped keys can access all resources within a pod (inboxes, threads, drafts, domains).
+
 <CodeBlocks>
   ```python
   # Create a key that can only access Acme's pod
@@ -4727,21 +5256,55 @@ This is useful when you want to hand a key to a tenant's service or agent withou
   ```
 </CodeBlocks>
 
+### Inbox-scoped keys
+
+Inbox-scoped keys are even more restrictive: they only grant access to a single inbox and its threads, messages, and drafts. Use these when an agent or integration only needs to operate on one address.
+
+<CodeBlocks>
+  ```python
+  # Create a key that can only access the support inbox
+  inbox_key = client.inboxes.api_keys.create(
+      inbox.inbox_id,
+      name="support-inbox-key"
+  )
+
+  print(inbox_key.api_key)
+  ```
+
+  ```typescript
+  const inboxKey = await client.inboxes.apiKeys.create(inbox.inboxId, {
+    name: "support-inbox-key",
+  });
+
+  console.log(inboxKey.apiKey);
+  ```
+</CodeBlocks>
+
 <Warning>
   The full API key is only returned **once** at creation. If you lose it, delete it and create a new one.
 </Warning>
 
-You can list and delete scoped keys for any pod:
+You can list and delete scoped keys for any pod or inbox:
 
 <CodeBlocks>
   ```python
+  # Pod-scoped keys
   keys = client.pods.api_keys.list(pod.pod_id)
   client.pods.api_keys.delete(pod.pod_id, scoped_key.api_key_id)
+
+  # Inbox-scoped keys
+  inbox_keys = client.inboxes.api_keys.list(inbox.inbox_id)
+  client.inboxes.api_keys.delete(inbox.inbox_id, inbox_key.api_key_id)
   ```
 
   ```typescript
+  // Pod-scoped keys
   const keys = await client.pods.apiKeys.list(pod.podId);
   await client.pods.apiKeys.delete(pod.podId, scopedKey.apiKeyId);
+
+  // Inbox-scoped keys
+  const inboxKeys = await client.inboxes.apiKeys.list(inbox.inboxId);
+  await client.inboxes.apiKeys.delete(inbox.inboxId, inboxKey.apiKeyId);
   ```
 </CodeBlocks>
 
@@ -4804,9 +5367,14 @@ Here's what onboarding a new tenant looks like end to end:
       )
       domain = client.pods.domains.create(pod.pod_id, domain=domain_name)
 
-      # Scoped key for the tenant
+      # Pod-scoped key for the tenant
       key = client.pods.api_keys.create(pod.pod_id, name=f"{tenant_id}-key")
 
+      # Inbox-scoped key for the support inbox
+      inbox_key = client.inboxes.api_keys.create(
+          inbox.inbox_id, name=f"{tenant_id}-support-key"
+      )
+
       # Webhook for their events
       webhook = client.webhooks.create(
           url=f"https://your-server.com/webhooks/{tenant_id}",
@@ -4817,7 +5385,8 @@ Here's what onboarding a new tenant looks like end to end:
       return {
           "pod_id": pod.pod_id,
           "inbox_id": inbox.inbox_id,
-          "api_key": key.api_key,  # deliver securely to tenant
+          "pod_api_key": key.api_key,  # deliver securely to tenant
+          "inbox_api_key": inbox_key.api_key,
           "webhook_id": webhook.webhook_id,
       }
   ```
@@ -4840,11 +5409,16 @@ Here's what onboarding a new tenant looks like end to end:
       domain: domainName,
     });
 
-    // Scoped key for the tenant
+    // Pod-scoped key for the tenant
     const key = await client.pods.apiKeys.create(pod.podId, {
       name: `${tenantId}-key`,
     });
 
+    // Inbox-scoped key for the support inbox
+    const inboxKey = await client.inboxes.apiKeys.create(inbox.inboxId, {
+      name: `${tenantId}-support-key`,
+    });
+
     // Webhook for their events
     const webhook = await client.webhooks.create({
       url: `https://your-server.com/webhooks/${tenantId}`,
@@ -4855,7 +5429,8 @@ Here's what onboarding a new tenant looks like end to end:
     return {
       podId: pod.podId,
       inboxId: inbox.inboxId,
-      apiKey: key.apiKey, // deliver securely to tenant
+      podApiKey: key.apiKey, // deliver securely to tenant
+      inboxApiKey: inboxKey.apiKey,
       webhookId: webhook.webhookId,
     };
   }
@@ -11201,6 +11776,514 @@ 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
+Content-Type: application/json
+
+Create a new agent organization with an inbox and API key. A 6-digit OTP is sent to the human's email for verification.
+
+This endpoint is idempotent. Calling it again with the same `human_email` will rotate the API key and resend the OTP if expired.
+
+The returned API key has limited permissions until the organization is verified via the verify endpoint.
+
+Reference: https://docs.agentmail.to/api-reference/agent/sign-up
+
+## OpenAPI Specification
+
+```yaml
+openapi: 3.1.0
+info:
+  title: api
+  version: 1.0.0
+paths:
+  /v0/agent/sign-up:
+    post:
+      operationId: sign-up
+      summary: Sign Up
+      description: >-
+        Create a new agent organization with an inbox and API key. A 6-digit OTP
+        is sent to the human's email for verification.
+
+
+        This endpoint is idempotent. Calling it again with the same
+        `human_email` will rotate the API key and resend the OTP if expired.
+
+
+        The returned API key has limited permissions until the organization is
+        verified via the verify endpoint.
+      tags:
+        - subpackage_agent
+      responses:
+        '200':
+          description: Response with status 200
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/type_agent:AgentSignupResponse'
+        '400':
+          description: Error response with status 400
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/type_:ValidationErrorResponse'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/type_agent:AgentSignupRequest'
+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_agent:AgentSignupRequest:
+      type: object
+      properties:
+        human_email:
+          type: string
+          description: >-
+            Email address of the human who owns the agent. A 6-digit OTP will be
+            sent to this address.
+        username:
+          type: string
+          description: >-
+            Username for the auto-created inbox (e.g. "my-agent" creates
+            my-agent@agentmail.to).
+      required:
+        - human_email
+        - username
+      description: Request body to sign up an agent.
+      title: AgentSignupRequest
+    type_agent:AgentSignupResponse:
+      type: object
+      properties:
+        organization_id:
+          type: string
+          description: ID of the created organization.
+        inbox_id:
+          type: string
+          description: ID of the auto-created inbox.
+        api_key:
+          type: string
+          description: >-
+            API key for authenticating subsequent requests. Store this securely,
+            it cannot be retrieved again.
+      required:
+        - organization_id
+        - inbox_id
+        - api_key
+      description: Response after successful agent sign-up.
+      title: AgentSignupResponse
+    type_:ErrorName:
+      type: string
+      description: Name of error.
+      title: ErrorName
+    type_:ValidationErrorResponse:
+      type: object
+      properties:
+        name:
+          $ref: '#/components/schemas/type_:ErrorName'
+        errors:
+          description: Validation errors.
+      required:
+        - name
+        - errors
+      title: ValidationErrorResponse
+
+```
+
+## SDK Code Examples
+
+```typescript
+import { AgentMailClient } from "agentmail";
+
+async function main() {
+    const client = new AgentMailClient();
+    await client.agent.signUp({
+        humanEmail: "human_email",
+        username: "username",
+    });
+}
+main();
+
+```
+
+```python
+from agentmail import AgentMail
+
+client = AgentMail()
+
+client.agent.sign_up(
+    human_email="human_email",
+    username="username",
+)
+
+```
+
+```go
+package main
+
+import (
+	"fmt"
+	"strings"
+	"net/http"
+	"io"
+)
+
+func main() {
+
+	url := "https://api.agentmail.to/v0/agent/sign-up"
+
+	payload := strings.NewReader("{\n  \"human_email\": \"human_email\",\n  \"username\": \"username\"\n}")
+
+	req, _ := http.NewRequest("POST", url, payload)
+
+	req.Header.Add("Content-Type", "application/json")
+
+	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/agent/sign-up")
+
+http = Net::HTTP.new(url.host, url.port)
+http.use_ssl = true
+
+request = Net::HTTP::Post.new(url)
+request["Content-Type"] = 'application/json'
+request.body = "{\n  \"human_email\": \"human_email\",\n  \"username\": \"username\"\n}"
+
+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.post("https://api.agentmail.to/v0/agent/sign-up")
+  .header("Content-Type", "application/json")
+  .body("{\n  \"human_email\": \"human_email\",\n  \"username\": \"username\"\n}")
+  .asString();
+```
+
+```php
+<?php
+require_once('vendor/autoload.php');
+
+$client = new \GuzzleHttp\Client();
+
+$response = $client->request('POST', 'https://api.agentmail.to/v0/agent/sign-up', [
+  'body' => '{
+  "human_email": "human_email",
+  "username": "username"
+}',
+  'headers' => [
+    'Content-Type' => 'application/json',
+  ],
+]);
+
+echo $response->getBody();
+```
+
+```csharp
+using RestSharp;
+
+var client = new RestClient("https://api.agentmail.to/v0/agent/sign-up");
+var request = new RestRequest(Method.POST);
+request.AddHeader("Content-Type", "application/json");
+request.AddParameter("application/json", "{\n  \"human_email\": \"human_email\",\n  \"username\": \"username\"\n}", ParameterType.RequestBody);
+IRestResponse response = client.Execute(request);
+```
+
+```swift
+import Foundation
+
+let headers = ["Content-Type": "application/json"]
+let parameters = [
+  "human_email": "human_email",
+  "username": "username"
+] as [String : Any]
+
+let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
+
+let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/agent/sign-up")! as URL,
+                                        cachePolicy: .useProtocolCachePolicy,
+                                    timeoutInterval: 10.0)
+request.httpMethod = "POST"
+request.allHTTPHeaderFields = headers
+request.httpBody = postData as Data
+
+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()
+```
+
+# Verify
+
+POST https://api.agentmail.to/v0/agent/verify
+Content-Type: application/json
+
+Verify an agent organization using the 6-digit OTP sent to the human's email during sign-up.
+
+On success, the organization is upgraded from `agent_unverified` to `agent_verified`, the send allowlist is removed, and free plan entitlements are applied.
+
+The OTP expires after 24 hours and allows a maximum of 10 attempts.
+
+Reference: https://docs.agentmail.to/api-reference/agent/verify
+
+## OpenAPI Specification
+
+```yaml
+openapi: 3.1.0
+info:
+  title: api
+  version: 1.0.0
+paths:
+  /v0/agent/verify:
+    post:
+      operationId: verify
+      summary: Verify
+      description: >-
+        Verify an agent organization using the 6-digit OTP sent to the human's
+        email during sign-up.
+
+
+        On success, the organization is upgraded from `agent_unverified` to
+        `agent_verified`, the send allowlist is removed, and free plan
+        entitlements are applied.
+
+
+        The OTP expires after 24 hours and allows a maximum of 10 attempts.
+      tags:
+        - subpackage_agent
+      parameters:
+        - 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_agent:AgentVerifyResponse'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/type_agent:AgentVerifyRequest'
+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_agent:AgentVerifyRequest:
+      type: object
+      properties:
+        otp_code:
+          type: string
+          description: 6-digit verification code sent to the human's email address.
+      required:
+        - otp_code
+      description: Request body to verify an agent with an OTP code.
+      title: AgentVerifyRequest
+    type_agent:AgentVerifyResponse:
+      type: object
+      properties:
+        verified:
+          type: boolean
+          description: Whether the organization was verified.
+      required:
+        - verified
+      description: Response after successful agent verification.
+      title: AgentVerifyResponse
+  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.agent.verify({
+        otpCode: "otp_code",
+    });
+}
+main();
+
+```
+
+```python
+from agentmail import AgentMail
+
+client = AgentMail(
+    api_key="YOUR_TOKEN_HERE",
+)
+
+client.agent.verify(
+    otp_code="otp_code",
+)
+
+```
+
+```go
+package main
+
+import (
+	"fmt"
+	"strings"
+	"net/http"
+	"io"
+)
+
+func main() {
+
+	url := "https://api.agentmail.to/v0/agent/verify"
+
+	payload := strings.NewReader("{\n  \"otp_code\": \"otp_code\"\n}")
+
+	req, _ := http.NewRequest("POST", url, payload)
+
+	req.Header.Add("Authorization", "Bearer <api_key>")
+	req.Header.Add("Content-Type", "application/json")
+
+	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/agent/verify")
+
+http = Net::HTTP.new(url.host, url.port)
+http.use_ssl = true
+
+request = Net::HTTP::Post.new(url)
+request["Authorization"] = 'Bearer <api_key>'
+request["Content-Type"] = 'application/json'
+request.body = "{\n  \"otp_code\": \"otp_code\"\n}"
+
+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.post("https://api.agentmail.to/v0/agent/verify")
+  .header("Authorization", "Bearer <api_key>")
+  .header("Content-Type", "application/json")
+  .body("{\n  \"otp_code\": \"otp_code\"\n}")
+  .asString();
+```
+
+```php
+<?php
+require_once('vendor/autoload.php');
+
+$client = new \GuzzleHttp\Client();
+
+$response = $client->request('POST', 'https://api.agentmail.to/v0/agent/verify', [
+  'body' => '{
+  "otp_code": "otp_code"
+}',
+  'headers' => [
+    'Authorization' => 'Bearer <api_key>',
+    'Content-Type' => 'application/json',
+  ],
+]);
+
+echo $response->getBody();
+```
+
+```csharp
+using RestSharp;
+
+var client = new RestClient("https://api.agentmail.to/v0/agent/verify");
+var request = new RestRequest(Method.POST);
+request.AddHeader("Authorization", "Bearer <api_key>");
+request.AddHeader("Content-Type", "application/json");
+request.AddParameter("application/json", "{\n  \"otp_code\": \"otp_code\"\n}", ParameterType.RequestBody);
+IRestResponse response = client.Execute(request);
+```
+
+```swift
+import Foundation
+
+let headers = [
+  "Authorization": "Bearer <api_key>",
+  "Content-Type": "application/json"
+]
+let parameters = ["otp_code": "otp_code"] as [String : Any]
+
+let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
+
+let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/agent/verify")! as URL,
+                                        cachePolicy: .useProtocolCachePolicy,
+                                    timeoutInterval: 10.0)
+request.httpMethod = "POST"
+request.allHTTPHeaderFields = headers
+request.httpBody = postData as Data
+
+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 Inboxes
 
 GET https://api.agentmail.to/v0/inboxes
@@ -21700,6 +22783,118 @@ components:
       type: string
       description: Name of api key.
       title: Name
+    type_api-keys:ApiKeyPermissions:
+      type: object
+      properties:
+        inbox_read:
+          type: boolean
+          description: Read inbox details.
+        inbox_create:
+          type: boolean
+          description: Create new inboxes.
+        inbox_update:
+          type: boolean
+          description: Update inbox settings.
+        inbox_delete:
+          type: boolean
+          description: Delete inboxes.
+        thread_read:
+          type: boolean
+          description: Read threads.
+        thread_delete:
+          type: boolean
+          description: Delete threads.
+        message_read:
+          type: boolean
+          description: Read messages.
+        message_send:
+          type: boolean
+          description: Send messages.
+        message_update:
+          type: boolean
+          description: Update message labels.
+        label_spam_read:
+          type: boolean
+          description: Access messages labeled spam.
+        label_blocked_read:
+          type: boolean
+          description: Access messages labeled blocked.
+        label_trash_read:
+          type: boolean
+          description: Access messages labeled trash.
+        draft_read:
+          type: boolean
+          description: Read drafts.
+        draft_create:
+          type: boolean
+          description: Create drafts.
+        draft_update:
+          type: boolean
+          description: Update drafts.
+        draft_delete:
+          type: boolean
+          description: Delete drafts.
+        draft_send:
+          type: boolean
+          description: Send drafts.
+        webhook_read:
+          type: boolean
+          description: Read webhook configurations.
+        webhook_create:
+          type: boolean
+          description: Create webhooks.
+        webhook_update:
+          type: boolean
+          description: Update webhooks.
+        webhook_delete:
+          type: boolean
+          description: Delete webhooks.
+        domain_read:
+          type: boolean
+          description: Read domain details.
+        domain_create:
+          type: boolean
+          description: Create domains.
+        domain_update:
+          type: boolean
+          description: Update domains.
+        domain_delete:
+          type: boolean
+          description: Delete domains.
+        list_entry_read:
+          type: boolean
+          description: Read list entries.
+        list_entry_create:
+          type: boolean
+          description: Create list entries.
+        list_entry_delete:
+          type: boolean
+          description: Delete list entries.
+        metrics_read:
+          type: boolean
+          description: Read metrics.
+        api_key_read:
+          type: boolean
+          description: Read API keys.
+        api_key_create:
+          type: boolean
+          description: Create API keys.
+        api_key_delete:
+          type: boolean
+          description: Delete API keys.
+        pod_read:
+          type: boolean
+          description: Read pods.
+        pod_create:
+          type: boolean
+          description: Create pods.
+        pod_delete:
+          type: boolean
+          description: Delete pods.
+      description: >-
+        Granular permissions for the API key. When ommitted all permissions are
+        granted. Otherwise, only permissions set to true are granted.
+      title: ApiKeyPermissions
     type_api-keys:CreatedAt:
       type: string
       format: date-time
@@ -21728,6 +22923,8 @@ components:
           type: string
           format: date-time
           description: Time at which api key was last used.
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
         created_at:
           $ref: '#/components/schemas/type_api-keys:CreatedAt'
       required:
@@ -21979,11 +23176,125 @@ components:
       type: string
       description: Name of api key.
       title: Name
+    type_api-keys:ApiKeyPermissions:
+      type: object
+      properties:
+        inbox_read:
+          type: boolean
+          description: Read inbox details.
+        inbox_create:
+          type: boolean
+          description: Create new inboxes.
+        inbox_update:
+          type: boolean
+          description: Update inbox settings.
+        inbox_delete:
+          type: boolean
+          description: Delete inboxes.
+        thread_read:
+          type: boolean
+          description: Read threads.
+        thread_delete:
+          type: boolean
+          description: Delete threads.
+        message_read:
+          type: boolean
+          description: Read messages.
+        message_send:
+          type: boolean
+          description: Send messages.
+        message_update:
+          type: boolean
+          description: Update message labels.
+        label_spam_read:
+          type: boolean
+          description: Access messages labeled spam.
+        label_blocked_read:
+          type: boolean
+          description: Access messages labeled blocked.
+        label_trash_read:
+          type: boolean
+          description: Access messages labeled trash.
+        draft_read:
+          type: boolean
+          description: Read drafts.
+        draft_create:
+          type: boolean
+          description: Create drafts.
+        draft_update:
+          type: boolean
+          description: Update drafts.
+        draft_delete:
+          type: boolean
+          description: Delete drafts.
+        draft_send:
+          type: boolean
+          description: Send drafts.
+        webhook_read:
+          type: boolean
+          description: Read webhook configurations.
+        webhook_create:
+          type: boolean
+          description: Create webhooks.
+        webhook_update:
+          type: boolean
+          description: Update webhooks.
+        webhook_delete:
+          type: boolean
+          description: Delete webhooks.
+        domain_read:
+          type: boolean
+          description: Read domain details.
+        domain_create:
+          type: boolean
+          description: Create domains.
+        domain_update:
+          type: boolean
+          description: Update domains.
+        domain_delete:
+          type: boolean
+          description: Delete domains.
+        list_entry_read:
+          type: boolean
+          description: Read list entries.
+        list_entry_create:
+          type: boolean
+          description: Create list entries.
+        list_entry_delete:
+          type: boolean
+          description: Delete list entries.
+        metrics_read:
+          type: boolean
+          description: Read metrics.
+        api_key_read:
+          type: boolean
+          description: Read API keys.
+        api_key_create:
+          type: boolean
+          description: Create API keys.
+        api_key_delete:
+          type: boolean
+          description: Delete API keys.
+        pod_read:
+          type: boolean
+          description: Read pods.
+        pod_create:
+          type: boolean
+          description: Create pods.
+        pod_delete:
+          type: boolean
+          description: Delete pods.
+      description: >-
+        Granular permissions for the API key. When ommitted all permissions are
+        granted. Otherwise, only permissions set to true are granted.
+      title: ApiKeyPermissions
     type_api-keys:CreateApiKeyRequest:
       type: object
       properties:
         name:
           $ref: '#/components/schemas/type_api-keys:Name'
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
       required:
         - name
       title: CreateApiKeyRequest
@@ -22018,6 +23329,8 @@ components:
         inbox_id:
           type: string
           description: Inbox ID the api key is scoped to.
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
         created_at:
           $ref: '#/components/schemas/type_api-keys:CreatedAt'
       required:
@@ -32163,6 +33476,118 @@ components:
       type: string
       description: Name of api key.
       title: Name
+    type_api-keys:ApiKeyPermissions:
+      type: object
+      properties:
+        inbox_read:
+          type: boolean
+          description: Read inbox details.
+        inbox_create:
+          type: boolean
+          description: Create new inboxes.
+        inbox_update:
+          type: boolean
+          description: Update inbox settings.
+        inbox_delete:
+          type: boolean
+          description: Delete inboxes.
+        thread_read:
+          type: boolean
+          description: Read threads.
+        thread_delete:
+          type: boolean
+          description: Delete threads.
+        message_read:
+          type: boolean
+          description: Read messages.
+        message_send:
+          type: boolean
+          description: Send messages.
+        message_update:
+          type: boolean
+          description: Update message labels.
+        label_spam_read:
+          type: boolean
+          description: Access messages labeled spam.
+        label_blocked_read:
+          type: boolean
+          description: Access messages labeled blocked.
+        label_trash_read:
+          type: boolean
+          description: Access messages labeled trash.
+        draft_read:
+          type: boolean
+          description: Read drafts.
+        draft_create:
+          type: boolean
+          description: Create drafts.
+        draft_update:
+          type: boolean
+          description: Update drafts.
+        draft_delete:
+          type: boolean
+          description: Delete drafts.
+        draft_send:
+          type: boolean
+          description: Send drafts.
+        webhook_read:
+          type: boolean
+          description: Read webhook configurations.
+        webhook_create:
+          type: boolean
+          description: Create webhooks.
+        webhook_update:
+          type: boolean
+          description: Update webhooks.
+        webhook_delete:
+          type: boolean
+          description: Delete webhooks.
+        domain_read:
+          type: boolean
+          description: Read domain details.
+        domain_create:
+          type: boolean
+          description: Create domains.
+        domain_update:
+          type: boolean
+          description: Update domains.
+        domain_delete:
+          type: boolean
+          description: Delete domains.
+        list_entry_read:
+          type: boolean
+          description: Read list entries.
+        list_entry_create:
+          type: boolean
+          description: Create list entries.
+        list_entry_delete:
+          type: boolean
+          description: Delete list entries.
+        metrics_read:
+          type: boolean
+          description: Read metrics.
+        api_key_read:
+          type: boolean
+          description: Read API keys.
+        api_key_create:
+          type: boolean
+          description: Create API keys.
+        api_key_delete:
+          type: boolean
+          description: Delete API keys.
+        pod_read:
+          type: boolean
+          description: Read pods.
+        pod_create:
+          type: boolean
+          description: Create pods.
+        pod_delete:
+          type: boolean
+          description: Delete pods.
+      description: >-
+        Granular permissions for the API key. When ommitted all permissions are
+        granted. Otherwise, only permissions set to true are granted.
+      title: ApiKeyPermissions
     type_api-keys:CreatedAt:
       type: string
       format: date-time
@@ -32191,6 +33616,8 @@ components:
           type: string
           format: date-time
           description: Time at which api key was last used.
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
         created_at:
           $ref: '#/components/schemas/type_api-keys:CreatedAt'
       required:
@@ -32406,11 +33833,125 @@ components:
       type: string
       description: Name of api key.
       title: Name
+    type_api-keys:ApiKeyPermissions:
+      type: object
+      properties:
+        inbox_read:
+          type: boolean
+          description: Read inbox details.
+        inbox_create:
+          type: boolean
+          description: Create new inboxes.
+        inbox_update:
+          type: boolean
+          description: Update inbox settings.
+        inbox_delete:
+          type: boolean
+          description: Delete inboxes.
+        thread_read:
+          type: boolean
+          description: Read threads.
+        thread_delete:
+          type: boolean
+          description: Delete threads.
+        message_read:
+          type: boolean
+          description: Read messages.
+        message_send:
+          type: boolean
+          description: Send messages.
+        message_update:
+          type: boolean
+          description: Update message labels.
+        label_spam_read:
+          type: boolean
+          description: Access messages labeled spam.
+        label_blocked_read:
+          type: boolean
+          description: Access messages labeled blocked.
+        label_trash_read:
+          type: boolean
+          description: Access messages labeled trash.
+        draft_read:
+          type: boolean
+          description: Read drafts.
+        draft_create:
+          type: boolean
+          description: Create drafts.
+        draft_update:
+          type: boolean
+          description: Update drafts.
+        draft_delete:
+          type: boolean
+          description: Delete drafts.
+        draft_send:
+          type: boolean
+          description: Send drafts.
+        webhook_read:
+          type: boolean
+          description: Read webhook configurations.
+        webhook_create:
+          type: boolean
+          description: Create webhooks.
+        webhook_update:
+          type: boolean
+          description: Update webhooks.
+        webhook_delete:
+          type: boolean
+          description: Delete webhooks.
+        domain_read:
+          type: boolean
+          description: Read domain details.
+        domain_create:
+          type: boolean
+          description: Create domains.
+        domain_update:
+          type: boolean
+          description: Update domains.
+        domain_delete:
+          type: boolean
+          description: Delete domains.
+        list_entry_read:
+          type: boolean
+          description: Read list entries.
+        list_entry_create:
+          type: boolean
+          description: Create list entries.
+        list_entry_delete:
+          type: boolean
+          description: Delete list entries.
+        metrics_read:
+          type: boolean
+          description: Read metrics.
+        api_key_read:
+          type: boolean
+          description: Read API keys.
+        api_key_create:
+          type: boolean
+          description: Create API keys.
+        api_key_delete:
+          type: boolean
+          description: Delete API keys.
+        pod_read:
+          type: boolean
+          description: Read pods.
+        pod_create:
+          type: boolean
+          description: Create pods.
+        pod_delete:
+          type: boolean
+          description: Delete pods.
+      description: >-
+        Granular permissions for the API key. When ommitted all permissions are
+        granted. Otherwise, only permissions set to true are granted.
+      title: ApiKeyPermissions
     type_api-keys:CreateApiKeyRequest:
       type: object
       properties:
         name:
           $ref: '#/components/schemas/type_api-keys:Name'
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
       required:
         - name
       title: CreateApiKeyRequest
@@ -32445,6 +33986,8 @@ components:
         inbox_id:
           type: string
           description: Inbox ID the api key is scoped to.
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
         created_at:
           $ref: '#/components/schemas/type_api-keys:CreatedAt'
       required:
@@ -41441,6 +42984,118 @@ components:
       type: string
       description: Name of api key.
       title: Name
+    type_api-keys:ApiKeyPermissions:
+      type: object
+      properties:
+        inbox_read:
+          type: boolean
+          description: Read inbox details.
+        inbox_create:
+          type: boolean
+          description: Create new inboxes.
+        inbox_update:
+          type: boolean
+          description: Update inbox settings.
+        inbox_delete:
+          type: boolean
+          description: Delete inboxes.
+        thread_read:
+          type: boolean
+          description: Read threads.
+        thread_delete:
+          type: boolean
+          description: Delete threads.
+        message_read:
+          type: boolean
+          description: Read messages.
+        message_send:
+          type: boolean
+          description: Send messages.
+        message_update:
+          type: boolean
+          description: Update message labels.
+        label_spam_read:
+          type: boolean
+          description: Access messages labeled spam.
+        label_blocked_read:
+          type: boolean
+          description: Access messages labeled blocked.
+        label_trash_read:
+          type: boolean
+          description: Access messages labeled trash.
+        draft_read:
+          type: boolean
+          description: Read drafts.
+        draft_create:
+          type: boolean
+          description: Create drafts.
+        draft_update:
+          type: boolean
+          description: Update drafts.
+        draft_delete:
+          type: boolean
+          description: Delete drafts.
+        draft_send:
+          type: boolean
+          description: Send drafts.
+        webhook_read:
+          type: boolean
+          description: Read webhook configurations.
+        webhook_create:
+          type: boolean
+          description: Create webhooks.
+        webhook_update:
+          type: boolean
+          description: Update webhooks.
+        webhook_delete:
+          type: boolean
+          description: Delete webhooks.
+        domain_read:
+          type: boolean
+          description: Read domain details.
+        domain_create:
+          type: boolean
+          description: Create domains.
+        domain_update:
+          type: boolean
+          description: Update domains.
+        domain_delete:
+          type: boolean
+          description: Delete domains.
+        list_entry_read:
+          type: boolean
+          description: Read list entries.
+        list_entry_create:
+          type: boolean
+          description: Create list entries.
+        list_entry_delete:
+          type: boolean
+          description: Delete list entries.
+        metrics_read:
+          type: boolean
+          description: Read metrics.
+        api_key_read:
+          type: boolean
+          description: Read API keys.
+        api_key_create:
+          type: boolean
+          description: Create API keys.
+        api_key_delete:
+          type: boolean
+          description: Delete API keys.
+        pod_read:
+          type: boolean
+          description: Read pods.
+        pod_create:
+          type: boolean
+          description: Create pods.
+        pod_delete:
+          type: boolean
+          description: Delete pods.
+      description: >-
+        Granular permissions for the API key. When ommitted all permissions are
+        granted. Otherwise, only permissions set to true are granted.
+      title: ApiKeyPermissions
     type_api-keys:CreatedAt:
       type: string
       format: date-time
@@ -41469,6 +43124,8 @@ components:
           type: string
           format: date-time
           description: Time at which api key was last used.
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
         created_at:
           $ref: '#/components/schemas/type_api-keys:CreatedAt'
       required:
@@ -41720,11 +43377,125 @@ components:
       type: string
       description: Name of api key.
       title: Name
+    type_api-keys:ApiKeyPermissions:
+      type: object
+      properties:
+        inbox_read:
+          type: boolean
+          description: Read inbox details.
+        inbox_create:
+          type: boolean
+          description: Create new inboxes.
+        inbox_update:
+          type: boolean
+          description: Update inbox settings.
+        inbox_delete:
+          type: boolean
+          description: Delete inboxes.
+        thread_read:
+          type: boolean
+          description: Read threads.
+        thread_delete:
+          type: boolean
+          description: Delete threads.
+        message_read:
+          type: boolean
+          description: Read messages.
+        message_send:
+          type: boolean
+          description: Send messages.
+        message_update:
+          type: boolean
+          description: Update message labels.
+        label_spam_read:
+          type: boolean
+          description: Access messages labeled spam.
+        label_blocked_read:
+          type: boolean
+          description: Access messages labeled blocked.
+        label_trash_read:
+          type: boolean
+          description: Access messages labeled trash.
+        draft_read:
+          type: boolean
+          description: Read drafts.
+        draft_create:
+          type: boolean
+          description: Create drafts.
+        draft_update:
+          type: boolean
+          description: Update drafts.
+        draft_delete:
+          type: boolean
+          description: Delete drafts.
+        draft_send:
+          type: boolean
+          description: Send drafts.
+        webhook_read:
+          type: boolean
+          description: Read webhook configurations.
+        webhook_create:
+          type: boolean
+          description: Create webhooks.
+        webhook_update:
+          type: boolean
+          description: Update webhooks.
+        webhook_delete:
+          type: boolean
+          description: Delete webhooks.
+        domain_read:
+          type: boolean
+          description: Read domain details.
+        domain_create:
+          type: boolean
+          description: Create domains.
+        domain_update:
+          type: boolean
+          description: Update domains.
+        domain_delete:
+          type: boolean
+          description: Delete domains.
+        list_entry_read:
+          type: boolean
+          description: Read list entries.
+        list_entry_create:
+          type: boolean
+          description: Create list entries.
+        list_entry_delete:
+          type: boolean
+          description: Delete list entries.
+        metrics_read:
+          type: boolean
+          description: Read metrics.
+        api_key_read:
+          type: boolean
+          description: Read API keys.
+        api_key_create:
+          type: boolean
+          description: Create API keys.
+        api_key_delete:
+          type: boolean
+          description: Delete API keys.
+        pod_read:
+          type: boolean
+          description: Read pods.
+        pod_create:
+          type: boolean
+          description: Create pods.
+        pod_delete:
+          type: boolean
+          description: Delete pods.
+      description: >-
+        Granular permissions for the API key. When ommitted all permissions are
+        granted. Otherwise, only permissions set to true are granted.
+      title: ApiKeyPermissions
     type_api-keys:CreateApiKeyRequest:
       type: object
       properties:
         name:
           $ref: '#/components/schemas/type_api-keys:Name'
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
       required:
         - name
       title: CreateApiKeyRequest
@@ -41759,6 +43530,8 @@ components:
         inbox_id:
           type: string
           description: Inbox ID the api key is scoped to.
+        permissions:
+          $ref: '#/components/schemas/type_api-keys:ApiKeyPermissions'
         created_at:
           $ref: '#/components/schemas/type_api-keys:CreatedAt'
       required:
@@ -42809,6 +44582,15 @@ const inbox = await client.inboxes.create();
 console.log(`Connected! Created inbox: ${inbox.inboxId}`);
 ```
 
+## Scoped API keys
+
+In addition to organization-level keys, you can create keys scoped to a single pod or inbox. Scoped keys restrict access so that the key can only operate on resources within that pod or inbox.
+
+* **Pod-scoped keys**: Create via `POST /pods/{pod_id}/api-keys` or `client.pods.api_keys.create()`
+* **Inbox-scoped keys**: Create via `POST /inboxes/{inbox_id}/api-keys` or `client.inboxes.api_keys.create()`
+
+See the [Multi-Tenancy guide](/multi-tenancy#scoped-api-keys) for details.
+
 ## Free tier
 
 No credit card required to get started. The free tier includes:
@@ -43430,6 +45212,7 @@ client.pods.delete(pod_id=pod.pod_id)
 * **Cross-pod email works normally.** Inboxes in different Pods can send and receive emails from each other, just like any other email addresses. Pods isolate data access, not email delivery.
 * **Inboxes cannot move between Pods.** If you need to reassign an inbox, create a new one in the target Pod.
 * **Pod-scoped API keys.** You can create API keys scoped to a specific Pod, so each tenant only has access to their own resources. Create them via `POST /pods/{pod_id}/api-keys`.
+* **Inbox-scoped API keys.** For even finer control, you can create keys scoped to a single inbox. These keys can only access that inbox's threads, messages, and drafts. Create them via `POST /inboxes/{inbox_id}/api-keys`.
 * **No limit on Pods.** You can create as many Pods as you need for your customers.
 * **Domains can be scoped to one Pod or all Pods.** A domain cannot be shared across a subset of Pods.