mail-operations

mail-operations Skill

L0: One-line Summary

Send and receive email, search, manage labels, and run automation rules via a local REST API; supports Gmail / Outlook / IMAP.

L1: Overview and Use Cases

Capability

mail-operations is a Procedural Skill that operates email systems through DesireCore's local REST API (called via the built-in MailOperations tool). It supports three mailbox types—Gmail (OAuth2), Outlook (MSAL), and IMAP/SMTP (QQ, 163, Yahoo, etc.)—covering send/receive, search, label management, attachment download, draft management, and automation rules.

Use Cases

• The user wants to view the inbox, send, or reply to email
• The user wants to search for specific emails or manage email labels/categories
• The user wants to download attachments or manage drafts
• The user wants to set up auto-reply rules or trigger an Agent to handle email

Core Value

• Unified interface: three mailbox types are operated through a unified API, lowering complexity
• Local and secure: all operations go through the local API; no need to expose credentials
• Smart integration: supports automation rules and Agent-based email handling

L2: Detailed Specification

How to Access the Email Service

Users can reach the email management interface via:

1. Click the third icon (folder icon) in the left navigation rail to open the Resource Explorer
2. On the Resource Explorer home page, find and click the "Emails" card to enter email management

If a user doesn't know how to open the email page, guide them through the steps above. They can also click "Open Resource Explorer" from the top-right corner of the chat interface, then select the Emails card.

---

API Basics

• How to call: use the built-in MailOperations tool. Its parameters are path (a relative path starting with /api/, with query parameters appended directly to it), method (default GET), body (a JSON object), and save_to (only for attachment downloads, see section 6). The tool locates the local Mail Service and attaches the access credential automatically; the Agent neither needs nor can supply a token.
• Path form: the endpoints below omit the /api prefix; add it when calling. For example, /imap/messages?email=me%40example.com&limit=20 becomes path: "/api/imap/messages?email=me%40example.com&limit=20". The only exception is the health check /ping (no /api).
• Do not connect to the port directly: do not curl https://127.0.0.1:62000. The port is allocated dynamically starting at 62000 (when several DesireCore instances run, 62000 may belong to another instance), and in strict capability mode direct requests without the credential always return 401.
• Parameter location: GET / DELETE parameters always go in the query string; for POST / PUT follow the tables below. The email of endpoints such as messages/fetch, mark as read/unread, Outlook single-message operations, and IMAP draft send must be in the query string; putting it in the body returns 400 Missing email parameter. For /sync, both provider and email must be in the query string: provider in the body returns 400 Invalid provider, and email alone in the body raises no parameter error but the sync does not take effect.
• Content-Type: application/json (set automatically by the tool when body is passed)
• Response format: success {"code": 1, "msg": "Success", "result": ...}, failure {"code": 0, "msg": "error message"}; some errors also carry a stable error code field error (e.g. smtp_unverified)