openapi: 3.2.0
info:
  title: Orthogonal API Marketplace Agent Mail API
  version: 1.0.0
  description: Discoverable APIs payable over MPP (Machine Payments Protocol / Tempo), x402, and np (Circle Gateway Nanopayments, x402 v2).
servers:
- url: https://mpp.orthogonal.com
  description: MPP (Tempo) rail
- url: https://x402.orthogonal.com
  description: x402 rail
- url: https://np.orthogonal.com
  description: np (Circle Gateway, x402 v2) rail
tags:
- name: AgentMail
paths:
  /agentmail/v0/inboxes/{inbox_id}/drafts/{draft_id}:
    get:
      operationId: agentmail_GET__v0_inboxes_inbox_id_drafts_draft_id_
      summary: Get a specific draft including its full content, recipients, and attachments.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
    delete:
      operationId: agentmail_DELETE__v0_inboxes_inbox_id_drafts_draft_id_
      summary: 'Permanently delete a draft. Important: pass method: "DELETE" in your run request.'
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
    patch:
      operationId: agentmail_PATCH__v0_inboxes_inbox_id_drafts_draft_id_
      summary: Update an existing draft. Only the fields you include will be changed; omitted fields are left unchanged.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes/{inbox_id}/drafts/{draft_id}/send:
    post:
      operationId: agentmail_POST__v0_inboxes_inbox_id_drafts_draft_id_send
      summary: Send an existing draft as an email. The draft is converted to a sent message and deleted from drafts. Returns the message_id and thread_id.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes/{inbox_id}:
    get:
      operationId: agentmail_GET__v0_inboxes_inbox_id_
      summary: Get details of a specific inbox including display name, creation date, and metadata.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
    patch:
      operationId: agentmail_PATCH__v0_inboxes_inbox_id_
      summary: Update an existing inbox display name or client ID.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
    delete:
      operationId: agentmail_DELETE__v0_inboxes_inbox_id_
      summary: 'Permanently delete an inbox and all its contents. Important: pass method: "DELETE" in your run request to distinguish from Get Inbox.'
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes/{inbox_id}/threads/{thread_id}:
    get:
      operationId: agentmail_GET__v0_inboxes_inbox_id_threads_thread_id_
      summary: Get a thread and all its messages. Returns the full conversation including message bodies, timestamps, and metadata.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
    delete:
      operationId: agentmail_DELETE__v0_inboxes_inbox_id_threads_thread_id_
      summary: 'Move a thread to trash, or permanently delete if already trashed. Important: pass method: "DELETE" in your run request.'
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/raw:
    get:
      operationId: agentmail_GET__v0_inboxes_inbox_id_messages_message_id_raw
      summary: Get the original raw RFC 2822 email content including all headers, MIME parts, and encoded attachments.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes/{inbox_id}/messages/{message_id}:
    patch:
      operationId: agentmail_PATCH__v0_inboxes_inbox_id_messages_message_id_
      summary: Update labels on a message (e.g., mark as read, archive, star).
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
    get:
      operationId: agentmail_GET__v0_inboxes_inbox_id_messages_message_id_
      summary: Get a specific message including headers, body (text and HTML), attachments, and metadata.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes/{inbox_id}/drafts:
    post:
      operationId: agentmail_POST__v0_inboxes_inbox_id_drafts
      summary: Create a new draft in an inbox. The draft can be edited later and sent with Send Draft.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
        '402':
          description: Payment Required (x402 / MPP / np)
      x-payment-info:
        price: 0.01
        offers:
        - method: mpp
          intent: charge
          rail: tempo
          currency: USDC.e
          url: https://mpp.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/drafts
        - method: x402
          intent: charge
          rail: base
          currency: USDC
          url: https://x402.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/drafts
        - method: np
          intent: charge
          rail: base
          currency: USDC
          settlement: circle-gateway
          version: x402-v2
          url: https://np.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/drafts
    get:
      operationId: agentmail_GET__v0_inboxes_inbox_id_drafts
      summary: List all drafts in an inbox. Returns draft metadata including subject, recipients, and timestamps.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/reply:
    post:
      operationId: agentmail_POST__v0_inboxes_inbox_id_messages_message_id_reply
      summary: Reply to a specific message. Automatically sets In-Reply-To and References headers for proper threading.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
        '402':
          description: Payment Required (x402 / MPP / np)
      x-payment-info:
        price: 0.01
        offers:
        - method: mpp
          intent: charge
          rail: tempo
          currency: USDC.e
          url: https://mpp.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/reply
        - method: x402
          intent: charge
          rail: base
          currency: USDC
          url: https://x402.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/reply
        - method: np
          intent: charge
          rail: base
          currency: USDC
          settlement: circle-gateway
          version: x402-v2
          url: https://np.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/reply
  /agentmail/v0/inboxes/{inbox_id}/messages/send:
    post:
      operationId: agentmail_POST__v0_inboxes_inbox_id_messages_send
      summary: Send an email message from an inbox. At least one recipient (to, cc, or bcc) is required. Returns the message_id and thread_id. Replace {inbox_id} directly in the path with the full inbox email (e.g., /v0/inboxes/myagent@agentmail.to/messages/send).
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
        '402':
          description: Payment Required (x402 / MPP / np)
      x-payment-info:
        price: 0.01
        offers:
        - method: mpp
          intent: charge
          rail: tempo
          currency: USDC.e
          url: https://mpp.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/send
        - method: x402
          intent: charge
          rail: base
          currency: USDC
          url: https://x402.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/send
        - method: np
          intent: charge
          rail: base
          currency: USDC
          settlement: circle-gateway
          version: x402-v2
          url: https://np.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/send
  /agentmail/v0/inboxes/{inbox_id}/threads:
    get:
      operationId: agentmail_GET__v0_inboxes_inbox_id_threads
      summary: List all email threads in an inbox, ordered by most recent. Supports pagination and filtering.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/forward:
    post:
      operationId: agentmail_POST__v0_inboxes_inbox_id_messages_message_id_forward
      summary: Forward a message to new recipients. Includes the original message content and any attachments.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
        '402':
          description: Payment Required (x402 / MPP / np)
      x-payment-info:
        price: 0.01
        offers:
        - method: mpp
          intent: charge
          rail: tempo
          currency: USDC.e
          url: https://mpp.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/forward
        - method: x402
          intent: charge
          rail: base
          currency: USDC
          url: https://x402.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/forward
        - method: np
          intent: charge
          rail: base
          currency: USDC
          settlement: circle-gateway
          version: x402-v2
          url: https://np.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/forward
  /agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all:
    post:
      operationId: agentmail_POST__v0_inboxes_inbox_id_messages_message_id_reply_all
      summary: Reply to all recipients of a message. Includes all original To and CC recipients automatically.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
        '402':
          description: Payment Required (x402 / MPP / np)
      x-payment-info:
        price: 0.01
        offers:
        - method: mpp
          intent: charge
          rail: tempo
          currency: USDC.e
          url: https://mpp.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all
        - method: x402
          intent: charge
          rail: base
          currency: USDC
          url: https://x402.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all
        - method: np
          intent: charge
          rail: base
          currency: USDC
          settlement: circle-gateway
          version: x402-v2
          url: https://np.orthogonal.com/agentmail/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all
  /agentmail/v0/inboxes/{inbox_id}/messages:
    get:
      operationId: agentmail_GET__v0_inboxes_inbox_id_messages
      summary: List all messages in an inbox, ordered by most recent. Supports pagination and filtering by labels or time range.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
  /agentmail/v0/inboxes:
    post:
      operationId: agentmail_POST__v0_inboxes
      summary: Create a new email inbox. Inboxes cost $2/month. Inboxes with no API activity for 30+ days are automatically deleted. Any request using the inbox resets the inactivity timer. Returns an inbox_id in email format (e.g., myagent@agentmail.to) used for all subsequent operations. If username is omitted, a random one is generated.
      tags:
      - AgentMail
      responses:
        '200':
          description: Successful response
        '402':
          description: Payment Required (x402 / MPP / np)
      x-payment-info:
        price: 2
        offers:
        - method: mpp
          intent: charge
          rail: tempo
          currency: USDC.e
          url: https://mpp.orthogonal.com/agentmail/v0/inboxes
        - method: x402
          intent: charge
          rail: base
          currency: USDC
          url: https://x402.orthogonal.com/agentmail/v0/inboxes
        - method: np
          intent: charge
          rail: base
          currency: USDC
          settlement: circle-gateway
          version: x402-v2
          url: https://np.orthogonal.com/agentmail/v0/inboxes
x-service-info:
  name: Orthogonal
  docs:
    llms: https://api.orthogonal.com/llms.txt
  protocols:
  - mpp
  - x402
  - np