Mails for Agent

Email Skill — Agent Auth-Completion

You have the email address $MAILS_MAILBOX. Your primary superpower: complete service registrations autonomously by receiving verification codes via GET /api/code?timeout=60.

Make HTTP requests to $MAILS_API_URL with header Authorization: Bearer $MAILS_AUTH_TOKEN.

Sign up for a service: Fill form with $MAILS_MAILBOX → GET /api/code?timeout=60 → enter the code. Done.

API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/inbox | List/search emails. Params: query, limit, offset, direction, label, mode (keyword/semantic/hybrid) | | GET | /api/email?id=ID | Full email with body, attachments, labels | | GET | /api/code?timeout=60 | Wait for verification code (long-poll). Params: timeout, since | | POST | /api/send | Send email. Body: { from, to[], cc[], bcc[], subject, text, html, reply_to, in_reply_to, headers, attachments } | | DELETE | /api/email?id=ID | Delete email and attachments | | GET | /api/attachment?id=ID | Download attachment | | GET | /api/threads | List conversation threads. Params: limit, offset | | GET | /api/thread?id=ID | Get all emails in a thread | | POST | /api/extract | Extract structured data. Body: { email_id, type } type: order/shipping/calendar/receipt/code | | GET | /api/stats | Mailbox statistics (total, inbound, outbound, this month) | | GET | /api/events | SSE real-time event stream. Params: types, since | | GET | /api/mailbox | Mailbox info (status, webhook_url) | | PATCH | /api/mailbox | Update mailbox settings. Body: { webhook_url } | | PATCH | /api/mailbox/pause | Pause mailbox (blocks all operations) | | PATCH | /api/mailbox/resume | Resume paused mailbox | | GET | /api/mailbox/routes | List per-label webhook routes | | PUT | /api/mailbox/routes | Upsert webhook route. Body: { label, webhook_url } | | DELETE | /api/mailbox/routes?label=X | Delete webhook route for label | | GET | /api/me | Mailbox info and capabilities | | GET | /health | Health check (no auth) |

Request Format

All requests (except /health) require Authorization: Bearer $MAILS_AUTH_TOKEN header.

POST/PUT/PATCH requests require Content-Type: application/json header.

The to param is optional — the API auto-scopes to the token's mailbox.

Response Shapes

Inbox: { "emails": [{ "id", "from_address", "from_name", "subject", "code", "direction", "status", "received_at", "has_attachments", "attachment_count" }], "search_mode": "keyword" }

Email detail: Full email object with body_text, body_html, headers, metadata, labels, thread_id, in_reply_to, references, attachments[]

Code: { "id": "...", "code": "483920", "from": "...", "subject": "...", "received_at": "..." } or { "code": null }

Send: { "id": "...", "provider_id": "...", "thread_id": "..." }

Threads: { "threads": [{ "thread_id", "latest_email_id", "subject", "from_address", "from_name", "received_at", "message_count", "has_attachments" }] }

Stats: { "mailbox", "total_emails", "inbound", "outbound", "emails_this_month", "ingest": { "pending", "parsed", "failed" } }

Extract: { "email_id": "...", "extraction": { "type": "order", "order_id": "...", ... } }

Events (SSE): event: message.received\ndata: { "email_id", "mailbox", "from", "subject", ... }

Send Fields

| Field | Required | Description | |-------|----------|-------------| | from | Yes | Must be $MAILS_MAILBOX (enforced server-side) | | to | Yes | Array of recipients (max 50) | | subject | Yes | Max 998 characters | | text | text or html | Plain text body | | html | text or html | HTML body | | cc | No | Array of CC recipients | | bcc | No | Array of BCC recipients | | replyto | No | Reply-to address | | inreply_to | No | Message-ID of parent email (enables threading) | | headers | No | Custom headers object | | attachments | No | [{ filename, content (base64), content_type?, content_id? }] |

Labels

Emails are auto-labeled on receive: newsletter, notification, code, personal. Filter with ?label=notification.

Common Flows

Sign up for a service: Fill form with $MAILS_MAILBOX → GET /api/code?timeout=60 → enter the code

Process inbox: GET /api/inbox → GET /api/email?id=ID → DELETE /api/email?id=ID

Reply to an email: GET /api/email?id=ID → POST /api/send with in_reply_to set to the email's message_id

View threads: GET /api/threads → GET /api/thread?id=THREAD_ID

Monitor in real-time: GET /api/events (SSE stream, reconnects automatically)

Extract data: POST /api/extract with {"email_id":"ID","type":"order"}

Set up webhook routing: PUT /api/mailbox/routes with {"label":"code","webhook_url":"https://..."}

Constraints

• from must match $MAILS_MAILBOX
• Verification codes: 4-12 alphanumeric (EN/ZH/JA/KO)
• Code wait timeout max 55 seconds
• Send rate limit: 100 emails/day per mailbox
• Search uses FTS5 full-text search (keyword mode) or Vectorize (semantic mode)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Digidai
• Source: Digidai/mails-skills
• License: MIT
• Homepage: https://mails0.com/

Install and usage instructions live in the source repository linked above.