# 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.