From 3a21b237f1fd15f34e05da0c7da751f231cd6157 Mon Sep 17 00:00:00 2001 From: armandokun Date: Fri, 19 Jun 2026 15:49:58 +0300 Subject: [PATCH] docs: document CC replies and the --cc / cc option Explain how to handle being CC'd on a thread: check deliveryRole and headerTo on inbound messages, reply to headerTo (not fromAddr), and how OpenMail auto-CCs the original sender. Document the cc send option (API) and --cc flag (CLI), plus that subject is optional on thread replies. Covers threading concept, OpenClaw integration, and the skill files. Co-authored-by: Cursor --- concepts/threading.mdx | 21 +++++++++++++++++++++ integrations/openclaw.mdx | 17 +++++++++++++---- integrations/skill-files/api.mdx | 5 +++++ skill.md | 10 ++++++++-- 4 files changed, 47 insertions(+), 6 deletions(-) diff --git a/concepts/threading.mdx b/concepts/threading.mdx index 0552d59..3563b67 100644 --- a/concepts/threading.mdx +++ b/concepts/threading.mdx @@ -25,6 +25,27 @@ This ensures your reply threads correctly in the recipient's email client (Gmail We also append a quoted copy of the previous message to the body by default (the familiar `On … wrote:` block with `>`-prefixed lines). Pass `includeQuote: false` to send only your reply text. +When replying with `threadId`, `subject` is optional — OpenMail uses the thread's subject (with a `Re:` prefix). Any subject you pass is ignored so recipient clients thread correctly. + +## Replying when you're CC'd + +Sometimes someone writes to one person and CCs your agent. For example, a customer replies to their contact and CCs your support inbox so you can chime in. OpenMail delivers the message to your inbox, but you may not be the person they addressed. + +When you fetch a thread (`GET /v1/threads/:id/messages` or `openmail threads get`), check each inbound message: + +- **`deliveryRole: "cc"`** — you were copied, not the main recipient. Send your reply to **`headerTo`** (who they wrote to), not **`fromAddr`** (who sent it). OpenMail automatically CCs **`fromAddr`** on thread replies so the person who looped you in stays on the thread. +- **`deliveryRole: "to"`** — your inbox was the main recipient. Reply to **`fromAddr`** as usual. + +To copy additional people on your reply, pass **`cc`** on send (API) or **`--cc`** on the CLI (repeatable). Explicit `cc` values are merged with the auto-CC. + +| Field | What it means | +|---|---| +| `fromAddr` | Who sent the email | +| `toAddr` | Your OpenMail inbox address | +| `headerTo` | Who the sender addressed (comma-separated if multiple) | +| `deliveryRole` | `to` if you were the main recipient, `cc` if you were copied | +| `cc` | Other people copied on the email | + ## Thread context Fetch all messages in a thread via `GET /v1/threads/:id/messages`. Messages are returned in chronological order, giving your agent the full conversation history to inform its next action. diff --git a/integrations/openclaw.mdx b/integrations/openclaw.mdx index cbd5c22..6209b52 100644 --- a/integrations/openclaw.mdx +++ b/integrations/openclaw.mdx @@ -105,15 +105,20 @@ openmail send --to "recipient@example.com" --subject "Report" --body "

See att `--body` accepts plain text or HTML — HTML is detected and rendered automatically. -Add `--attach ` to attach files (repeatable). The response includes -`messageId` and `threadId` — store `threadId` to continue the conversation -later. Subject is ignored when replying in a thread. +Add `--attach ` to attach files (repeatable). Add `--cc ` (repeatable) +to copy other recipients. The response includes `messageId` and `threadId` — +store `threadId` to continue the conversation later. `--subject` is optional +when replying with `--thread-id` — OpenMail uses the thread subject automatically. **Always reply in the existing thread.** When the user asks you to reply to an email, look up the thread with `openmail inbox` or `openmail threads list` first, then use `--thread-id`. Never create a new thread unless the user explicitly asks for one. +**When you were CC'd:** run `openmail threads get` and check `deliveryRole`. +If it is `cc`, reply to `headerTo` (who they wrote to), not `fromAddr` (who sent it). +OpenMail auto-CCs `fromAddr` on thread replies so they stay on the conversation. + ## Checking for new mail **Always use `threads list --is-read false` to check for new mail.** @@ -164,7 +169,11 @@ Each message has: |---|---| | `id` | Message identifier | | `threadId` | Conversation thread | -| `fromAddr` | Sender address | +| `fromAddr` | Who sent the email | +| `toAddr` | Your OpenMail inbox address | +| `headerTo` | Who the sender addressed (use for CC replies) | +| `deliveryRole` | `to` if you were the main recipient, `cc` if you were copied | +| `cc` | Other people copied on the email | | `subject` | Subject line | | `bodyText` | Plain text body (use this) | | `attachments` | Array with `filename`, `url`, `sizeBytes` | diff --git a/integrations/skill-files/api.mdx b/integrations/skill-files/api.mdx index 3903114..94f54ce 100644 --- a/integrations/skill-files/api.mdx +++ b/integrations/skill-files/api.mdx @@ -117,6 +117,9 @@ Message object: "inboxId": "inb_...", "fromAddr": "Alice ", "toAddr": "agent@openmail.sh", + "headerTo": "bob@example.com", + "deliveryRole": "cc", + "cc": ["agent@openmail.sh"], "subject": "Hello", "bodyText": "Plain text content", "bodyHtml": "

HTML content

", @@ -132,6 +135,8 @@ Message object: } ``` +When `deliveryRole` is `cc`, reply to `headerTo` — not `fromAddr`. OpenMail auto-CCs `fromAddr` on thread replies. + ### Inboxes ```bash diff --git a/skill.md b/skill.md index 78e7ea2..eda4803 100644 --- a/skill.md +++ b/skill.md @@ -28,10 +28,12 @@ openmail send \ --body "Plain text body." ``` -Reply in a thread with `--thread-id thr_...`. Put HTML directly in `--body` — it is detected and rendered automatically. Attach files with `--attach ` (repeatable). The response includes `messageId` and `threadId` — store `threadId` to continue the conversation later. +Reply in a thread with `--thread-id thr_...`. `--subject` is optional when replying — the thread subject is used automatically. Add `--cc addr` (repeatable) to copy other recipients. Put HTML directly in `--body` — it is detected and rendered automatically. Attach files with `--attach ` (repeatable). The response includes `messageId` and `threadId` — store `threadId` to continue the conversation later. **Always reply in the existing thread.** When the user asks you to reply to an email, look up the thread with `openmail threads list` first, then use `--thread-id`. Never create a new thread unless the user explicitly asks for one. +**When you were CC'd:** run `openmail threads get` and check `deliveryRole` on the inbound message. If it is `cc`, reply to `headerTo` (who they wrote to), not `fromAddr` (who sent it). OpenMail auto-CCs `fromAddr` on thread replies so they stay on the conversation. + ## Checking for new mail **Always use `threads list --is-read false` to check for new mail.** This returns only unread threads — emails you haven't processed yet. @@ -76,7 +78,11 @@ Each message has: |---|---| | `id` | Message identifier | | `threadId` | Conversation thread | -| `fromAddr` | Sender address | +| `fromAddr` | Who sent the email | +| `toAddr` | Your OpenMail inbox address | +| `headerTo` | Who the sender addressed (use for CC replies) | +| `deliveryRole` | `to` if you were the main recipient, `cc` if you were copied | +| `cc` | Other people copied on the email | | `subject` | Subject line | | `bodyText` | Plain text body (use this) | | `attachments` | Array with `filename`, `url`, `sizeBytes` |