sgmail-skill/skills/internal-mail-agent/SKILL.md

name, description

name	description
internal-mail-agent	Use when Codex or another agent needs to work with an internal/local mailbox through the internal-mail-skill REST adapter: syncing POP3 mail, searching and reading email, managing local read/processed/archived/replied state, labels, drafts, replies, forwards, or sending through SMTP when Gmail/IMAP tools are unavailable and the local adapter is running or can be started.

Internal Mail Agent

Use the local REST adapter as the mailbox backend. The adapter usually runs at http://127.0.0.1:8765 and stores POP3 mail, local state, labels, drafts, and sent records in SQLite.

Before Use

1. Resolve the base URL from the user, INTERNAL_MAIL_SKILL_BASE_URL, or default to http://127.0.0.1:8765.
2. Call GET /health. If it fails, ask the user to start the adapter or start it from the repo with go run ./cmd/server when local context allows.
3. Treat POP3 server state as one-way input. Read, processed, archived, deleted, replied, labels, drafts, and sent records are local adapter state only.
4. Never expose attachment storage paths. Use only attachment_id, filename, content type, and size returned by the API.

Common Workflow

• For fresh mailbox work, call POST /sync first unless the user explicitly wants local-only results.
• For triage, use GET /emails/search with filters, then read only the messages needed with GET /emails/{id}.
• For threads, call GET /emails/{id}/thread; the adapter assembles local threads from Message-ID, In-Reply-To, and References.
• For organization, use POST /emails/{id}/mark, POST /labels, and POST /emails/labels/apply.
• For composing, prefer POST /drafts and show the draft summary before sending unless the user explicitly requested immediate send.
• For explicit sends, use POST /drafts/{id}/send or POST /send. The adapter writes every attempt to sent_messages.

Sending Rules

• Do not send email unless the user has clearly asked to send, reply, or forward.
• Include to, cc, and bcc arrays in requests as needed. Bcc participates in SMTP delivery but must not appear in message headers.
• For replies, pass reply_to_email_id when creating the draft so the adapter can set In-Reply-To and References and mark the source email replied after successful send.
• If send fails, surface the structured error and do not claim the message was sent.
• SMTP delivery does not guarantee the message appears in Webmail "Sent".

API Reference

For request shapes, query parameters, response notes, and curl examples, read references/http-api.md.