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

[sweetmantech]

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.

^{Written for commit f66a4cd. Summary will update on new commits.}

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.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds OpenAPI documentation for a new POST /api/emails endpoint, plus a dedicated Send Email docs page and an Accounts navigation entry that links to it.

Changes

Send Email docs

Layer / File(s)	Summary
Endpoint contract api-reference/openapi/accounts.json	Adds SendEmailRequest and EmailResponse, and documents POST /api/emails with request, success, and error responses.
Page and navigation api-reference/emails/create.mdx, docs.json	Adds a Send Email MDX page and an Emails group under the Accounts docs navigation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• recoupable/docs#48: Adds the same POST /api/emails OpenAPI entry and the matching Emails navigation group in docs.json.

Poem

A rabbit hopped by, ears held high,
To greet a Send Email page in the sky.
The docs now point, the schemas gleam,
A fresh API path joins the stream.
🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the new documentation contract for POST /api/emails.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/emails-endpoint-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@api-reference/emails/create.mdx`:
- Line 3: The frontmatter in create.mdx has an invalid openapi value because it
includes the spec file path along with the operation. Update the openapi
metadata to use only the METHOD /path form, matching the expected format used by
the docs system, and ensure the value references the email creation route
directly rather than the OpenAPI file path.

In `@api-reference/openapi/accounts.json`:
- Around line 2857-2876: Mark the EmailResponse schema fields as required so
generated clients treat success, message, and id as always present. Update the
EmailResponse object definition in accounts.json to include a required array
containing those three properties, keeping the existing property definitions and
examples unchanged.
- Around line 2802-2812: The `to` schema in the account email payload currently
permits an empty array even though the endpoint contract requires one or more
recipients. Update the `to` array definition in the OpenAPI spec to enforce a
minimum of one item, keeping the existing email item type and description
intact, so the schema matches the “one or more recipients” requirement.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7e952c43-0eaa-4c8f-9788-85beac613562

📥 Commits

Reviewing files that changed from the base of the PR and between 83754b8 and a14a96b.

📒 Files selected for processing (3)

• api-reference/emails/create.mdx
• api-reference/openapi/accounts.json
• docs.json

[coderabbitai]

🎯 Functional Correctness | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify current openapi frontmatter patterns across API reference pages.
rg -n '^openapi:\s*' api-reference --glob '**/*.mdx'

Repository: recoupable/docs

Length of output: 16458

---

Remove the OpenAPI spec file path from the openapi frontmatter value.

The openapi value is currently set to the spec file path combined with the method and route, but the required format is strictly METHOD /path (e.g., POST /api/emails).

- openapi: "/api-reference/openapi/accounts.json POST /api/emails"
+ openapi: "POST /api/emails"

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	openapi: "/api-reference/openapi/accounts.json POST /api/emails"
	openapi: "POST /api/emails"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/emails/create.mdx` at line 3, The frontmatter in create.mdx has
an invalid openapi value because it includes the spec file path along with the
operation. Update the openapi metadata to use only the METHOD /path form,
matching the expected format used by the docs system, and ensure the value
references the email creation route directly rather than the OpenAPI file path.

Source: Coding guidelines

[cubic-dev-ai]

1 issue found across 3 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[sweetmantech]

KISS - Do not mention 3rd party integrations. Remove excessive details from the description.

Suggested change

	"description": "Send an email to one or more recipients via the Resend API. Emails are sent from `Agent by Recoup <agent@recoupable.com>`. The request is account-scoped from the API key or Bearer token. Supports plain text (rendered as Markdown) or raw HTML bodies, optional CC recipients, custom headers, and an optional room_id to include a chat link in the email footer.",
	"description": "Send an email to one or more recipients. Emails are sent from `Agent by Recoup <agent@recoupable.com>`.,

[sweetmantech]

What do you think about changing this from the legacy room_id to the new chat_id to match our new session / chat architecture?

[sweetmantech]

Pushed 52b00fa115f7d040e76f5d46a623d60935655021 addressing the review:

• room_id → chat_id (your comment): renamed the public field to match the new session/chat architecture — the footer already links to /chat/{id}, so the value is a chat id. Docs-only for now: api#708 still validates room_id (it reuses processAndSendEmail → selectRoomWithArtist, which queries the legacy rooms table). I'll re-anchor api#708 to rename the request field to chat_id before it merges (internal rooms lookup can stay), and update skills#57 to match. Flagged on api#708.
• Description KISS (your comment): trimmed to Send an email to one or more recipients. Emails are sent from \Agent by Recoup agent@recoupable.com`.` — dropped the Resend mention and the per-field prose.
• to minItems: 1 (CodeRabbit + cubic): added.
• EmailResponse required {success, message, id} (CodeRabbit): added.
• Skipped CodeRabbit's create.mdx openapi frontmatter suggestion (POST /api/emails only). The repo convention is "/api-reference/openapi/<spec>.json METHOD /path" — used by ~26 pages (e.g. accounts/id.mdx, workspaces/create.mdx). The current value already matches it; the bare form would break the spec reference.

[cubic-dev-ai]

2 issues found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/accounts.json">

<violation number="1" location="api-reference/openapi/accounts.json:913">
P2: Custom agent: **Documentation and Naming Conventions for Maintainable Code**

Endpoint description was shortened, removing critical consumer-facing details about supported content types, CC recipients, custom headers, chat link integration, email provider, and auth scoping.</violation>

<violation number="2" location="api-reference/openapi/accounts.json:2847">
P2: Custom agent: **Documentation and Naming Conventions for Maintainable Code**

Naming inconsistency: `SendEmailRequest` uses `chat_id` while `CreateNotificationRequest` uses `room_id` for the same conceptual feature (including a chat link in the email footer). Related schemas should use consistent field names for identical concepts.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Custom agent: Documentation and Naming Conventions for Maintainable Code

Naming inconsistency: SendEmailRequest uses chat_id while CreateNotificationRequest uses room_id for the same conceptual feature (including a chat link in the email footer). Related schemas should use consistent field names for identical concepts.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/accounts.json, line 2847:

<comment>Naming inconsistency: `SendEmailRequest` uses `chat_id` while `CreateNotificationRequest` uses `room_id` for the same conceptual feature (including a chat link in the email footer). Related schemas should use consistent field names for identical concepts.</comment>

<file context>
@@ -2843,9 +2844,9 @@
             "description": "Optional custom email headers"
           },
-          "room_id": {
+          "chat_id": {
             "type": "string",
-            "description": "Room ID to include a chat link in the email footer"
</file context>

[cubic-dev-ai]

P2: Custom agent: Documentation and Naming Conventions for Maintainable Code

Endpoint description was shortened, removing critical consumer-facing details about supported content types, CC recipients, custom headers, chat link integration, email provider, and auth scoping.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/accounts.json, line 913:

<comment>Endpoint description was shortened, removing critical consumer-facing details about supported content types, CC recipients, custom headers, chat link integration, email provider, and auth scoping.</comment>

<file context>
@@ -910,7 +910,7 @@
     "/api/emails": {
       "post": {
-        "description": "Send an email to one or more recipients via the Resend API. Emails are sent from `Agent by Recoup <agent@recoupable.com>`. The request is account-scoped from the API key or Bearer token. Supports plain text (rendered as Markdown) or raw HTML bodies, optional CC recipients, custom headers, and an optional room_id to include a chat link in the email footer.",
+        "description": "Send an email to one or more recipients. Emails are sent from `Agent by Recoup <agent@recoupable.com>`.",
         "requestBody": {
           "description": "Email payload",
</file context>

Suggested change

	"description": "Send an email to one or more recipients. Emails are sent from `Agent by Recoup <agent@recoupable.com>`.",
	+ "description": "Send an email to one or more recipients via the Resend API. Emails are sent from `Agent by Recoup <agent@recoupable.com>`. The request is account-scoped from the API key or Bearer token. Supports plain text (rendered as Markdown) or raw HTML bodies, optional CC recipients, custom headers, and an optional chat_id to include a chat link in the email footer."