Add agent skill package

skills/internal-mail-agent/references/http-api.md

@@ -0,0 +1,135 @@
+# Internal Mail Adapter HTTP API
+
+Default base URL: `http://127.0.0.1:8765`.
+
+All errors use:
+
+```json
+{"error":{"code":"code","message":"message","details":{}}}
+```
+
+## Health and Sync
+
+`GET /health`
+
+Returns service status, version, database status, account ID, and current time.
+
+`POST /sync`
+
+Fetches POP3 messages with UIDL de-duplication. Does not delete server mail. Single-message failures appear in `errors[]` and do not stop the whole sync.
+
+## Search and Read
+
+`GET /emails/search`
+
+Supported query parameters:
+
+- `q`
+- `from`
+- `to`
+- `after`
+- `before`
+- `has_attachment`
+- `read`
+- `processed`
+- `archived`
+- `replied`
+- `limit`
+- `offset`
+
+Returns summaries only: subject, sender, recipients, dates, snippet, local status, labels, and attachment count.
+
+Example:
+
+```bash
+curl "http://127.0.0.1:8765/emails/search?q=合同&from=alice@example.local&has_attachment=true&limit=20"
+```
+
+`GET /emails/{id}`
+
+Returns full local email detail: subject, from, to, cc, date, body text, body HTML, attachments, local status, labels, and thread headers. Attachments expose `attachment_id`, filename, content type, content ID, and size; do not expect or request filesystem paths.
+
+`GET /emails/{id}/thread`
+
+Returns local thread summaries. A message joins the thread when its `In-Reply-To` or `References` contains another local message's `Message-ID`.
+
+## Local State and Labels
+
+`POST /emails/{id}/mark`
+
+Body fields are optional booleans:
+
+```json
+{"read":true,"processed":true,"archived":false,"deleted":false,"replied":true}
+```
+
+These states are local only and are not synchronized back to POP3.
+
+`POST /labels`
+
+```json
+{"name":"待处理","color":"#336699"}
+```
+
+`POST /emails/labels/apply`
+
+```json
+{"email_ids":[1],"label_ids":[1],"op":"add"}
+```
+
+Use `"op":"remove"` to remove labels.
+
+## Drafts and Sending
+
+`POST /drafts`
+
+```json
+{
+  "to":["bob@example.local"],
+  "cc":[],
+  "bcc":[],
+  "subject":"测试",
+  "body":"你好",
+  "reply_to_email_id":1
+}
+```
+
+`reply_to_email_id` is optional. Use it for replies.
+
+`GET /drafts`
+
+Lists local drafts.
+
+`PATCH /drafts/{id}`
+
+Uses the same body shape as `POST /drafts`.
+
+`POST /drafts/{id}/send`
+
+Sends a draft by SMTP. On success, the adapter marks the draft `sent`, writes `sent_messages(status=sent)`, and marks the source email replied when the draft is a reply. On failure, it writes `sent_messages(status=failed,error_message=...)` and leaves the draft unsent.
+
+`POST /send`
+
+Direct send. Uses the same request shape as `POST /drafts`, internally creating and sending a draft.
+
+`POST /emails/{id}/forward`
+
+```json
+{
+  "to":["bob@example.local"],
+  "cc":[],
+  "bcc":[],
+  "subject":"Fwd: 原邮件",
+  "body":"请看下面原文",
+  "include_attachments":false
+}
+```
+
+Attachment forwarding is reserved for a later version. `include_attachments=true` returns a structured error.
+
+## Agent Notes
+
+- Prefer summaries for scanning and read full bodies only when needed.
+- Do not infer server-side read/unread from local status.
+- Do not claim SMTP-sent messages appear in Webmail Sent.
+- If `/sync` returns message-level errors, report counts and the affected UID/server ID instead of treating the whole sync as failed.