docs: POST /api/emails (send-email) contract

Merged
SW
4mo ago
+156-0

Contract for recoupable/chat#1815 — Item 1 (send-email API so the sandbox agent can deliver email). Docs-first: this is the contract the api implementation fulfills.

What this adds

  • OpenAPI (api-reference/openapi/accounts.json): POST /api/emails path + two schemas — SendEmailRequest (mirrors CreateNotificationRequest but adds a required to[] recipient array) and EmailResponse ({ success, message, id }). Reuses the shared #/components/schemas/Error for 400/401/502.
  • Reference page (api-reference/emails/create.mdx): frontmatter-only, per house rule.
  • Nav: new "Emails" group in the Accounts tab.

Why a new endpoint vs /api/notifications

POST /api/notifications only emails the authenticated account's own address. The agent needs to send to an explicit recipient (the report's audience) — the same capability the legacy send_email MCP tool had. So this mirrors notifications but takes to[].

Merge order

docs (this) → api (implements POST /api/emails, links back here) → skills (documents it for the agent). Part of #1815 Item 1.

Diff is additive (140 insertions in the OpenAPI file; both JSON files re-validated to parse).

Summary by cubic

Add the docs-first contract for POST /api/emails so the sandbox agent can send email to explicit recipients. Notes that to/cc are limited to the account’s own email without a payment method on file. Contract for recoupable/chat#1815 Item 1.

  • New Features
    • OpenAPI: add /api/emails with SendEmailRequest and EmailResponse; require to (min 1) and success, message, id; reuse #/components/schemas/Error for 400/401/502.
    • Recipient policy: document to/cc restrictions and link to /api-reference/credits/sessions-create to lift them.
    • Docs: add api-reference/emails/create.mdx and an "Emails" group under Accounts.
    • Polish: simplify the endpoint description; rename room_id to chat_id; link chat_id to Create Chat.

Summary by CodeRabbit

  • New Features

    • Added documentation for a new email-sending API endpoint.
    • Published request and response details for sending emails, including recipients, subject, content, and optional headers.

  • Documentation

    • Added a dedicated “Send Email” page in the API reference.
    • Updated the Accounts navigation to include a new Emails section.