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

Internal Mail Adapter HTTP API

Default base URL: http://127.0.0.1:8765.

All errors use:

{"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:

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:

{"read":true,"processed":true,"archived":false,"deleted":false,"replied":true}

These states are local only and are not synchronized back to POP3.

POST /labels

{"name":"待处理","color":"#336699"}

POST /emails/labels/apply

{"email_ids":[1],"label_ids":[1],"op":"add"}

Use "op":"remove" to remove labels.

Drafts and Sending

POST /drafts

{
  "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

{
  "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.