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

# Mailbox

> Search a connected mailbox and read its attachments

Read a firm's Outlook or Gmail mailbox through its chosen [connection](https://docs.oneshotagent.com/api-reference/connections/overview.md). List `GET /v1/connections` first and choose `connection_id` by `system` and `account_label`. These tools only read. Message snippets, attachment metadata and bytes pass through the response; OneShot never writes them to logs, receipts, jobs or goal history.

## Search messages

`POST /v1/tools/mailbox/messages` (`mailbox_messages`) requires `connection_id`, a non-empty `query`, and inclusive received dates `from` and `to` (`YYYY-MM-DD`). Optional `sender` is an email address; `has_attachments` is a boolean. `limit` defaults to 25 and must be between 1 and 50. Pass the previous `next_cursor` as `cursor`, keeping the filters unchanged.

```json theme={null}
{
  "connection_id": "00000000-0000-4000-8000-000000000001",
  "query": "invoice",
  "from": "2026-10-01",
  "to": "2026-10-31",
  "has_attachments": true,
  "limit": 25
}
```

The response is `{ "success": true, "data": { "records": [], "receipt_id": "..." } }`, with `next_cursor` when another page exists. Each record contains `id`, `received_at`, `sender` (`name`, `address`), `subject`, `snippet` (at most 300 characters), `attachments` (`id`, `name`, `content_type`, `size`) and `source` (`system`, `id`). This route never returns full message bodies or attachment bytes. Missing descriptive fields are null.

## Read an attachment

`POST /v1/tools/mailbox/attachment` (`mailbox_attachment`) takes `connection_id`, `message_id` and `attachment_id` from the search results. It returns `name`, `content_type`, `size` and `base64` inside `data`, alongside `receipt_id`. Only file attachments are supported. Gmail supports attachments whose bytes are included in the message MIME payload. Attachments stored separately by Gmail are currently refused before payment. Gmail search still lists their metadata.

Content is limited to 10 MB (10,485,760 bytes). Missing, invalid or oversized metadata refuses before payment. The actual decoded bytes are checked too. If the attachment changes or a read fails after payment, the read receipt owns the refund as account credit.

Malformed inputs return `400 invalid_request`. Another agent's connection is `404 connection_not_found`; revoked or expired connections return 409. Unsupported content returns `400 not_supported`; unavailable mailboxes return 503. Payment uses x402 or account credit; amounts are on [Pricing](https://docs.oneshotagent.com/pricing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.