136 lines
3.1 KiB
Markdown
136 lines
3.1 KiB
Markdown
# 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.
|