Use the OS mail integration to query the user's native macOS Mail.app — listing mailboxes and accounts, searching messages, reading message bodies and attachments, and sending new mail through the configured accounts. Use even when you think you know the answer — inbox state is dynamic; only the live API reflects current messages, unread counts, and folder organization. Do not use for: web-based mail (Gmail/Outlook web), non-macOS systems, email protocol questions (IMAP/SMTP), or generic email-marketing/composition advice.
Best use case
mail is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use the OS mail integration to query the user's native macOS Mail.app — listing mailboxes and accounts, searching messages, reading message bodies and attachments, and sending new mail through the configured accounts. Use even when you think you know the answer — inbox state is dynamic; only the live API reflects current messages, unread counts, and folder organization. Do not use for: web-based mail (Gmail/Outlook web), non-macOS systems, email protocol questions (IMAP/SMTP), or generic email-marketing/composition advice.
Teams using mail should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/mail/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How mail Compares
| Feature / Agent | Standard Approach | |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use the OS mail integration to query the user's native macOS Mail.app — listing mailboxes and accounts, searching messages, reading message bodies and attachments, and sending new mail through the configured accounts. Use even when you think you know the answer — inbox state is dynamic; only the live API reflects current messages, unread counts, and folder organization. Do not use for: web-based mail (Gmail/Outlook web), non-macOS systems, email protocol questions (IMAP/SMTP), or generic email-marketing/composition advice.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
Mail access goes through the Speedwave MCP Hub. Claude does not see `mail__*` tools directly — use `search_tools` to discover them and `execute_code` with the injected `os` global to invoke. Tools are called as `await os.<methodName>({ … })`.
macOS Mail.app unifies all accounts configured in **System Settings → Internet Accounts** — iCloud, Gmail, Exchange, IMAP, and others are all accessible through the same `os.listMailboxes` / `os.listEmails` surface. No per-account credentials are needed; the mcp-os worker uses Automation permission (TCC), pre-validated on first enable.
## Workflow
1. `search_tools({ query: "mail", detail_level: "names_only", service: "os" })` — discover what is available.
2. `search_tools({ query: "os__<toolName>", detail_level: "full_schema", service: "os" })` — get the exact parameter schema.
3. `execute_code` — call the tool using the parameter names from the schema.
Always run steps 1–2 before guessing a tool name or parameter. The live schema is the source of truth.
## Pitfalls
- **`os.*`, not `mail.*`.** All four OS sub-services (mail, calendar, reminders, notes) share the same `os` global. There is no `mail` global.
- **Mailbox names are case-sensitive** and may be nested (e.g. `INBOX/Work/Clients`). Call `os.listMailboxes` first to get exact names; do not guess folder paths.
- **Listing returns metadata only.** `os.listEmails` returns subject, sender, date, and read-status — not the full body. Retrieve the body with a separate `os.getEmail({ id })` call. Be selective; fetching many bodies in a loop can be slow and token-heavy.
- **`confirm_send` is mandatory for writes.** Both `os.sendEmail` and `os.replyToEmail` require `confirm_send: true` in the payload — the parameter is a hard gate in the Swift CLI, not just a convention. Per the global write/delete confirmation rule in CLAUDE.md, always show the user a summary of subject, recipients, and body before calling these tools; never set `confirm_send: true` without explicit user approval.
- **Sending is irreversible.** Once `os.sendEmail` or `os.replyToEmail` returns `{ "status": "sent" }`, the message is in the MTA queue. There is no undo. Drafts (compose without send) are not exposed as a tool; if the user only wants to draft, explain this limitation.
- **Attachments are not returned inline.** The current tool surface does not decode MIME attachments; if attachment content is needed, note this limitation to the user.
- **Search scope.** `os.searchEmails` searches the inbox only (subject and body content). For searches across all mailboxes, list target mailboxes with `os.listMailboxes` first and iterate with `os.listEmails({ mailbox })`.
- **Microsoft Outlook.** If Outlook is installed and running, pass `client: "outlook"` to redirect calls to it. The default is Apple Mail.
## When NOT to use
- Web-based mail accessed through a browser (no native Mail.app account configured).
- IMAP/SMTP server configuration questions — those belong in System Settings.
- Generic email-writing or marketing-copy advice — no tool call needed.Related Skills
speedwave-product-showcase
Build a self-contained, dependency-free animated "live product" demo for a landing page — a step carousel that faithfully recreates the real app UI (chat, settings, integrations, logs…) using only HTML + scoped CSS + one inline rAF script. Use when asked to add an animated product walkthrough / hero demo / "show the app in motion" to a marketing site.
sharepoint
Use SharePoint integration to read, write, and manage files, lists, list items, columns, and pages on the configured Microsoft 365 site. Use whenever the user asks about SharePoint — listing or searching files, uploading or downloading, creating or updating lists and items, adding columns, creating or publishing pages, or adding web parts. Use even when you think you know the answer — site state is dynamic; only the live API reflects current files, list items, or page versions. Do not use for: Microsoft 365 Outlook/Teams/OneDrive operations not surfaced via SharePoint, cross-site or cross-tenant ops (only the configured site), or generic Microsoft Graph questions.
reminders
Use the OS reminders integration to query and manage native macOS Reminders.app — listing reminder lists, fetching reminders by list or due date, creating new reminders, updating, completing, or deleting them. Use even when you think you know the answer — Reminders state is dynamic; only the live API reflects current items, due dates, and completion status. Do not use for: non-macOS systems, other reminder/task apps (Todoist, TickTick, etc.), or anything outside the user's local Reminders.app.
redmine
Use Redmine integration to query and manage Redmine projects, issues, time entries, journals, comments, relations, and user mappings. Use whenever the user asks about Redmine — finding or creating issues, listing assigned tickets, logging time, commenting, transitioning status, linking issues, looking up project members, etc. Use even when you think you know the answer — issue and project state are dynamic; only the live API reflects current assignments, status, or time entries. Do not use for: project management theory, anything outside the configured Redmine instance, or wiki content (no wiki tools available — use playwright or paste the URL).
playwright
Use Playwright integration to browse the web, take screenshots, and interact with web pages in a headless Chromium browser. Use whenever the user asks to screenshot a page, navigate to a URL, check what is on a website, fill a form, click through a flow, or extract content from a rendered page. Use even when you think you know the page content — websites change constantly; only the live browser reflects current rendering, JS-injected content, and dynamic state. Do not use for: fetching plain HTML or JSON that does not need JavaScript rendering (use WebFetch), scraping that violates the site's terms of service, anything requiring credentials the user has not provided, or local file access (the Playwright container has no /workspace mount).
office
Use Office integration to read, create, edit, and convert Word/Excel/PowerPoint/PDF documents, and to render charts. Use whenever the user asks about working with .docx, .xlsx, .pptx, or .pdf files — reading content, creating reports or invoices, editing existing documents, converting between formats, merging or splitting PDFs, or rendering charts. Use even when you think you know the answer — document libraries change between framework versions; only the live tool reflects current Office/PDF format support and chart rendering capabilities. Do not use for: plain text files (read them directly), generic Markdown conversion that does not need PDF output (use built-in tools), or installing document-processing libraries — they are already behind office__* tools.
notes
Use the OS notes integration to query and manage native macOS Notes.app — listing folders and accounts, searching notes by title or body, reading note content, creating new notes, updating existing notes, and deleting notes. Use even when you think you know the answer — Notes state is dynamic; only the live API reflects current content, folder structure, and iCloud-sync updates. Do not use for: non-macOS systems, other note apps (Obsidian, Bear, Logseq, Notion, etc.), or generic note-taking-methodology advice.
gitlab
Use GitLab integration to query and manage projects, merge requests, issues, pipelines, branches, commits, files, and releases on the configured GitLab instance. Use whenever the user asks about GitLab — listing MRs, reviewing diffs, opening or merging MRs, creating/closing issues, comparing branches, reading pipeline status, fetching files, searching code, etc. Use even when you think you know the answer — repository state is dynamic and only the live API reflects current MR status, pipeline runs, or issue assignments. Do not use for: plain git operations on the local checkout, GitHub.com (use github), general code review questions, or anything outside the configured GitLab instance.
github
Use GitHub integration to query and manage GitHub.com repositories, pull requests, issues, branches, commits, Actions workflow runs, labels, tags, and releases. Use whenever the user asks about GitHub — opening or reviewing PRs, getting PR diffs, listing or commenting on issues, comparing branches, reading workflow logs, creating releases, searching code, etc. Use even when you think you know the answer — repository state is dynamic; only the live API reflects current PR status, workflow runs, or issue assignments. Do not use for: plain git operations on the local checkout, GitLab or self-hosted GitHub Enterprise (out of scope), general code review questions, or any repo not on GitHub.com.
context7
Use Context7 to fetch current library/framework/API/SDK/CLI/cloud-service documentation whenever the user asks about a named technology — including setup, configuration, code examples, version migration, library-specific debugging, best practices, and "is X the right way to do Y" questions. Covers popular technologies such as React, Next.js, Angular, Vue, Svelte, Prisma, Drizzle, Express, NestJS, FastAPI, Django, Flask, Spring Boot, Tailwind, shadcn/ui, and any other named library, SDK, API, CLI tool, or cloud service. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.
calendar
Use the OS calendar integration to query and manage native macOS Calendar.app — listing calendars, fetching events by date range, creating/updating/deleting events, and checking availability. Use even when you think you know the answer — calendar state is dynamic; only the live API reflects current events, RSVP status, and shared-calendar updates. Do not use for: non-macOS systems, third-party calendar services (Google Calendar API directly, Outlook web, etc.) — those go through their own integrations if configured.
atlassian
Use Atlassian integration to query and manage Jira Cloud and Confluence Cloud — Jira issues, comments, transitions, assignments, agile boards/sprints, and Confluence pages, spaces, labels, attachments. Use whenever the user asks about Jira tickets/issues/sprints or Confluence pages/spaces — searching with JQL/CQL, getting or creating issues, transitioning workflows, finding or updating pages, etc. Use even when you think you know the answer — issue and page state are dynamic; only the live API reflects current assignments, transitions, comments, or page revisions. Do not use for: self-hosted Jira/Confluence Server or Data Center (Cloud only), generic project management theory, or anything outside the configured Atlassian site.