docs: document CC replies and the --cc / cc option

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.

integrations/openclaw.mdx

@@ -105,15 +105,20 @@ openmail send --to "recipient@example.com" --subject "Report" --body "<p>See att
 
 `--body` accepts plain text or HTML — HTML is detected and rendered automatically.
 
-Add `--attach <path>` 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 <path>` to attach files (repeatable). Add `--cc <email>` (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` |

integrations/skill-files/api.mdx

@@ -117,6 +117,9 @@ Message object:
   "inboxId": "inb_...",
   "fromAddr": "Alice <alice@example.com>",
   "toAddr": "agent@openmail.sh",
+  "headerTo": "bob@example.com",
+  "deliveryRole": "cc",
+  "cc": ["agent@openmail.sh"],
   "subject": "Hello",
   "bodyText": "Plain text content",
   "bodyHtml": "<p>HTML content</p>",
@@ -132,6 +135,8 @@ Message object:
 }
 ```
 
+When `deliveryRole` is `cc`, reply to `headerTo` — not `fromAddr`. OpenMail auto-CCs `fromAddr` on thread replies.
+
 ### Inboxes
 
 ```bash

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 <path>` (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 <path>` (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` |