> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentpost.email/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP API

> Use the AgentPost MCP server to give AI agents full control over mailboxes, email, domains, and sending.

AgentPost exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server so AI agents can create mailboxes, read emails, send messages, and manage custom domains — all through a standard tool-calling interface.

**MCP in plain terms:** MCP is an open standard that lets AI agents call tools hosted on a server, the same way a human uses an API. Your agent describes what it wants, and the server executes it and returns structured results. No scraping, no custom integrations.

## Endpoint

| Property       | Value                            |
| -------------- | -------------------------------- |
| URL            | `/mcp`                           |
| Protocol       | JSON-RPC 2.0 via HTTP POST       |
| Authentication | Bearer token                     |
| Rate limit     | 60 requests per minute per token |

## Discovery

* **Machine-readable:** `/.well-known/mcp.json` — for MCP clients that auto-discover tools
* **Human/AI-readable:** `/mcp/docs` — browsable documentation for the full tool schema

## Available tools

<CardGroup cols={2}>
  <Card title="CreateMailbox" icon="plus">
    Create a new temporary mailbox. Optionally specify a verified custom domain to enable outbound sending.
  </Card>

  <Card title="ListMailboxEmails" icon="list">
    List all emails in a mailbox, with optional body inclusion and thread grouping.
  </Card>

  <Card title="ReadEmail" icon="envelope-open">
    Read the full content of a specific email, including attachments metadata.
  </Card>

  <Card title="DeleteEmail" icon="trash">
    Permanently delete a specific email message.
  </Card>

  <Card title="DeleteMailbox" icon="inbox">
    Delete a mailbox and all its messages.
  </Card>

  <Card title="WaitForEmail" icon="clock">
    Wait for an email to arrive, streaming progress every 2 seconds until the message is received or the timeout expires.
  </Card>

  <Card title="DownloadAttachment" icon="paperclip">
    Download a specific email attachment by its UUID as base64-encoded content.
  </Card>

  <Card title="ListThreads" icon="comments">
    List conversation threads in a mailbox, sorted by latest activity with cursor-based pagination.
  </Card>

  <Card title="ReadThread" icon="comment">
    Read all messages in a conversation thread in chronological order.
  </Card>

  <Card title="AddDomain" icon="globe">
    Add a custom domain to your account and get DNS records to configure.
  </Card>

  <Card title="ListDomains" icon="list-check">
    List all custom domains and their verification and sending status.
  </Card>

  <Card title="VerifyDomain" icon="circle-check">
    Trigger DNS verification for a domain. Passes the domain into warmup once all checks pass.
  </Card>

  <Card title="RemoveDomain" icon="xmark">
    Remove a custom domain from your account.
  </Card>

  <Card title="SendEmail" icon="paper-plane">
    Send an outbound email from a mailbox on a verified custom domain.
  </Card>
</CardGroup>

## Typical use cases

**Sign-up verification:** Create a mailbox → use the address to sign up for a service → call `WaitForEmail` → extract the verification link from the response.

**Outbound email automation:** Add and verify a custom domain → create a mailbox on it → call `SendEmail` to queue delivery.

**Inbox monitoring:** Call `ListMailboxEmails` to scan for messages, `ReadEmail` to read specific ones, and `ListThreads` + `ReadThread` to follow full conversations.

**Cleanup after automation:** Call `DeleteEmail` to remove individual messages or `DeleteMailbox` to tear down the entire inbox when your workflow completes.