Mails for Agent

Send and receive emails via HTTP API. Use when the agent needs to: sign up for services and enter verification codes, monitor an inbox for incoming messages,...

Security Scan

The skill's requested env vars, instructions, and lack of install steps align with its stated purpose (HTTP access to an email API); main remaining risk is trusting the remote email service and the auth token you provide.

Purpose & Capability

Name/description (send/receive emails via HTTP API) match the declared requirements: MAILS_API_URL, MAILS_AUTH_TOKEN, MAILS_MAILBOX. No unrelated credentials, binaries, or config paths are requested. primaryEnv=MAILS_AUTH_TOKEN is appropriate.

Instruction Scope

SKILL.md contains a focused HTTP API contract (endpoints, params, response shapes) and instructs use of only the declared environment variables. It does not instruct reading unrelated files, scanning system state, or transmitting data to other endpoints beyond MAILS_API_URL.

Install Mechanism

No install spec and no bundled code — instruction-only skill. This is lowest-risk for persistence and code execution since nothing is written to disk by the skill itself.

Credentials

Requires three env vars that are directly relevant (API base URL, bearer auth token, mailbox identifier). No extraneous secrets or broad system credentials are requested.

Persistence & Privilege

always:false and no install mean the skill does not force permanent inclusion. Model invocation is enabled (default), so an agent could autonomously call the mail API when this skill is used — this is normal but worth noting because it grants the agent the ability to send/delete/read mailbox data using the provided token.

Assessment

This skill appears internally consistent and only needs an API URL, an auth token, and a mailbox address — which is expected for an HTTP email service. Before installing, verify you trust the MAILS_API_URL operator and that the MAILS_AUTH_TOKEN has minimal scope and an expiration if possible. Consider: (1) who runs the API and their privacy/security posture; (2) what the agent will be allowed to do with the mailbox (send, delete, read attachments) and whether you permit autonomous agent actions; (3) storing the token in a secure secret store and rotating it regularly; and (4) enabling logging/auditing or restricting the agent's capability if you want to limit automated signups or message deletion. If you need higher assurance, request the API's documentation or a known provider domain and check for TLS and scoped credentials.

Email Skill

You have the email address $MAILS_MAILBOX. Make HTTP requests to $MAILS_API_URL with header Authorization: Bearer $MAILS_AUTH_TOKEN.

API Endpoints

Method	Endpoint	Description
GET	/api/inbox	List emails. Params: query, limit, offset, direction, label, mode
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[], subject, text, html, 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: to, limit, offset
GET	/api/thread?id=ID	Get all emails in a thread. Params: to
POST	/api/extract	Extract structured data. Body: { email_id, type } type: order/shipping/calendar/receipt/code
GET	/api/search?q=TEXT	Semantic/hybrid search. Params: mode (keyword/semantic/hybrid)
GET	/api/me	Worker info and capabilities
GET	/health	Health check (no auth)

Request Format

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

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

Inbox query params: to=$MAILS_MAILBOX is required for mailbox scoping.

Response Shapes

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

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

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

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

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

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
reply_to	No	Reply-to address
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

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

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

Constraints

• from must match $MAILS_MAILBOX
• Verification codes: 4-8 alphanumeric (EN/ZH/JA/KO)
• Code wait timeout max 55 seconds
• Search uses FTS5 full-text search (keyword mode) or Vectorize (semantic mode)