docs: make `to` and `subject` optional on POST /api/emails

Merged
SW
4mo ago
+2-6

Contract change for the "make `to` optional on `POST /api/emails`" follow-up enhancement on chat#1815 (decided 2026-06-25). Docs-first — this is the contract recoupable/api implements next.

What changed

SendEmailRequest in api-reference/openapi/accounts.json:

  • to removed from required (only subject remains required).
  • to.description now documents the default: when omitted, the email is sent to the authenticated account's own email address.

to keeps minItems: 1 (when provided, at least one recipient). The no-card recipient restriction is unchanged — the account's own email is always allowed without a card, so the default recipient never trips the 403.

Why

So a caller can "email me this" without restating their own address — the common scheduled-report case. This also lets POST /api/emails fully subsume POST /api/notifications (self-send), which chat#1815 then deletes.

Merge order

docs (this) → api (to optional in sendEmailBodySchema, resolve account_emails when omitted).

Minimal additive diff (1 insertion, 2 deletions); JSON validated.

🤖 Generated with Claude Code

Summary by cubic

Make to and subject optional on POST /api/emails; omitting to sends to the authenticated account’s own email, and omitting subject defaults to the first heading/line of the body, falling back to Message from Recoup if empty.

OpenAPI docs updated: SendEmailRequest now has no required fields; when provided, to still must include at least one recipient and the no-card restriction is unchanged (own email always allowed).