Skip to main content
POST
Mailbox
Read a firm’s Outlook mailbox through its chosen connection. 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.
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. 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.