> ## 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.

# Mailbox Tools

> MCP tools for creating, listing, and deleting mailboxes and threads.

## CreateMailbox

Creates a new email mailbox for your account. Optionally specify a custom domain to create a mailbox that can send outbound email. Optionally specify a custom name for the local part of the address.

Each call creates a new mailbox — this tool is not idempotent.

**Inputs**

<ParamField path="domain" type="string">
  A verified custom domain you own (e.g., `"example.com"`). Omit to use the default AgentPost domain. Only mailboxes on custom domains can send outbound email. The domain must be in `active`, `pending_warmup`, or `pending_dns` status.
</ParamField>

<ParamField path="name" type="string">
  Custom local part for the email address (e.g., `"support"` creates `support@domain.com`). Must be 3-64 characters, alphanumeric with dots and hyphens only. Only allowed on custom domains — omit for a randomly generated name.
</ParamField>

<Note>
  Mailboxes can be created on domains in `pending_dns` status, but they will not be able to send email until the domain passes DNS verification and reaches `pending_warmup` or `active` status.
</Note>

**Output**

<ResponseField name="id" type="string">
  Unique identifier for the mailbox.
</ResponseField>

<ResponseField name="email_address" type="string">
  The generated email address (e.g., `calm.brook-42@agent.agentpost.email`).
</ResponseField>

<ResponseField name="domain" type="string">
  The domain the mailbox was created on.
</ResponseField>

<ResponseField name="can_send" type="boolean">
  Whether the mailbox can send outbound email. `true` only for mailboxes on custom domains in a sendable state.
</ResponseField>

<ResponseField name="mx_verified" type="boolean">
  Whether the domain has MX records verified for inbound email reception. Only relevant for custom domain mailboxes.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the mailbox was created.
</ResponseField>

***

## ListMailboxEmails

Lists all emails in a mailbox. Returns up to 50 most recent messages. You must own the mailbox.

**Inputs**

<ParamField path="email_address" type="string" required>
  The email address of the mailbox to list emails for.
</ParamField>

<ParamField path="include_body" type="boolean">
  When `true`, includes `text_content` for each message. Prefers `html2text`-converted content, falling back to plain text or stripped HTML. Defaults to `false`.
</ParamField>

<ParamField path="group_by_thread" type="boolean">
  When `true`, returns thread summaries instead of individual messages — same format as `ListThreads`. Defaults to `false`.
</ParamField>

**Output**

<ResponseField name="mailbox" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the mailbox.
    </ResponseField>

    <ResponseField name="email_address" type="string">
      The mailbox email address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message_count" type="integer">
  Total number of messages returned.
</ResponseField>

<ResponseField name="messages" type="array">
  List of message summaries. Each message includes `id`, `subject`, `from`, `date`, `preview`, `thread_id`, and optionally `text_content` when `include_body` is `true`.
</ResponseField>

<Note>
  When `group_by_thread` is `true`, the response matches the `ListThreads` format: `{ mailbox, thread_count, threads, next_cursor }`.
</Note>

***

## DeleteMailbox

Deletes a mailbox and all of its messages. You must own the mailbox.

<Warning>
  This action is irreversible. All messages in the mailbox are permanently deleted.
</Warning>

**Inputs**

<ParamField path="email_address" type="string" required>
  The email address of the mailbox to delete.
</ParamField>

**Output**

<ResponseField name="deleted" type="boolean">
  Always `true` when the mailbox was successfully deleted.
</ResponseField>

<ResponseField name="email_address" type="string">
  The email address of the deleted mailbox.
</ResponseField>

***

## ListThreads

Lists conversation threads in a mailbox, grouped and sorted by latest activity. Returns compact thread summaries with no message bodies, optimized for minimal token usage.

**Inputs**

<ParamField path="email_address" type="string" required>
  The mailbox email address to list threads for.
</ParamField>

<ParamField path="cursor" type="string">
  Opaque pagination cursor. Pass the `next_cursor` value from a previous response to fetch the next page.
</ParamField>

<ParamField path="limit" type="integer">
  Maximum number of threads to return. Must be between 1 and 50. Defaults to `20`.
</ParamField>

**Output**

<ResponseField name="mailbox" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the mailbox.
    </ResponseField>

    <ResponseField name="email_address" type="string">
      The mailbox email address.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="thread_count" type="integer">
  Number of threads returned in this response.
</ResponseField>

<ResponseField name="threads" type="array">
  List of thread summaries, sorted by latest message date descending. Each thread includes `thread_id`, `subject`, `message_count`, `latest_date`, `latest_preview`, `participants`, and `has_attachments`.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Cursor for the next page of results. `null` when there are no more threads.
</ResponseField>

<Note>
  Use `ReadThread` to fetch the full conversation content for a specific thread. Single-message threads have `message_count: 1`.
</Note>

***

## ReadThread

Reads all messages in a conversation thread in chronological order (oldest first). You must own the thread's mailbox.

**Inputs**

<ParamField path="thread_id" type="string" required>
  The thread ID to read. Obtain this from `ListThreads` or from the `thread_id` field in other tool responses.
</ParamField>

<ParamField path="format" type="string">
  Response format for message content. Options: `text`, `html`, `html2text`. Defaults to `"html2text"`.

  * `html2text` — HTML converted to clean readable text preserving links and structure. Recommended for AI agents.
  * `text` — original plain text part.
  * `html` — both plain text and full HTML content.
</ParamField>

<ParamField path="limit" type="integer">
  When set, returns only the latest N messages in chronological order. Omit to get all messages. Maximum 100.
</ParamField>

**Output**

<ResponseField name="thread_id" type="string">
  The thread identifier.
</ResponseField>

<ResponseField name="subject" type="string">
  The thread subject line.
</ResponseField>

<ResponseField name="message_count" type="integer">
  Total number of messages in the thread.
</ResponseField>

<ResponseField name="messages" type="array">
  Messages in chronological order. Each message includes `id`, `subject`, `from`, `to`, `cc`, `date`, `direction`, `text_content`, `has_attachments`, `attachment_count`, and optionally `attachments`.

  The `direction` field is either `"inbound"` or `"outbound"`.
</ResponseField>