operations / skill

Desktop Mail Assistant

Read, search, draft, and send through the Mail app with a full-message approval check.

By Zero Width Lab

Like Save

First uploaded 7 Sept 2026Listing updated 8 Sept 2026

At a glance

Purpose: Read, search, draft, and send through the Mail app with a full-message approval check.
Runs in: Local agent with shell
Operating systems: macOS
Needs: Runtime: Python 3.10+, standard library and osascript only; Needs internet: Yes; Needs accounts or API keys beyond your agent: Yes
Files and data: Reads files: Yes; Writes files: No; Sends data to other services: Yes
Tool type: Skill
Delivery: Download from Skills Outpost
Version: 0.1.0
ZIP SHA-256: 10040adbe1aead4330f03078c5d8c7ebba4f16e2a9c02274b86b8ba2b109d828
Access: Download from Skills Outpost
Compatibility: macOS with Apple's Mail app, Python 3.10 or newer, and an Agent Skills compatible harness that can run local Python commands. Uses only the Python standard library and /usr/bin/osascript. Mail accounts must already be configured. The CLI makes no direct network request. Unsupported platforms fail before body-file, fixture or Mail I/O, including dry runs.
External costs: The package is free under the MIT license and has no service fee. Mail provider fees, if any, are set by the user's existing account provider.
Permissions: macOS Automation permission lets the calling terminal or agent harness control Mail. The CLI uses the user's configured Mail accounts and reads no account secret. Send and draft read only the caller-selected UTF-8 --body-file; no local output file is written. Test only: DESKTOP_MAIL_FAKE_RESPONSES and DESKTOP_MAIL_FAKE_TRANSPORT_TEST_ACK=1 select a synthetic fixture and replace osascript. The CLI invokes /usr/bin/osascript. It has no direct network access; Mail may sync with the provider hosts configured for each user account. Package hygiene reads package text only. Unsupported systems fail before I/O.
Usage terms: MIT license. Copyright 2026 Zero Width Lab. Apple, Mac, macOS and Mail are trademarks of Apple Inc. This product is independent and is not affiliated with or endorsed by Apple Inc. By Zero Width Lab (zerowidthlab.com)

Download from Skills Outpost

Get this version

Free

Version 0.1.0 · Skill package (ZIP) · 66.8 KiB

Released 8 Sept 2026

Static source, format, secret-pattern and declaration checks with independent human source review.

SHA-256 of the released ZIP: 10040adbe1aead4330f03078c5d8c7ebba4f16e2a9c02274b86b8ba2b109d828

The creator shows this version's package files publicly: anyone can read SKILL.md and the other files under Files, without an account. The ZIP download needs the version in your Library (how it works).

A creator follow is free, not a paid membership. Your email is not shared with the creator.

Files

Version 0.1.0, shown publicly by its creator, exactly as in this version's ZIP. ZIP SHA-256: 10040adbe1aead4330f03078c5d8c7ebba4f16e2a9c02274b86b8ba2b109d828. License: MIT (read it).

Each file has its own address. Read one as a web page at https://skillsoutpost.com/agents/desktop-mail-assistant-5b25e540/files?path=SKILL.md, or as JSON at https://skillsoutpost.com/api/v1/catalog/desktop-mail-assistant-5b25e540/files?path=SKILL.md; replace SKILL.md with any path below.

MIT

MIT License

Copyright (c) 2026 Zero Width Lab

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Version history

Version 0.1.0 Current
Released 8 Sept 2026
No release notes for this version.

What it does

Desktop Mail Assistant is a command-line Agent Skill for reading and composing messages through Apple's Mail app on macOS. An agent harness is software that installs the skill, runs local commands, and presents results to a user. It needs Python 3.10 or newer, a configured Mail account, and macOS Automation permission. It is free under the MIT license. This listing delivers the complete package with scripts.

The CLI lists accounts and mailboxes, shows recent messages, searches by subject or sender in a chosen mailbox, and reads one message by Mail message ID with a body limit. It also previews a full outgoing message or draft, including all recipients and the body. Approval-gated means a write requires the digest of that exact preview plus the user's explicit approval. A send correlates against the first 100 entries in the selected account's Sent mailbox without proving delivery or this specific attempt; a missing verification leaves the outcome uncertain and must be inspected before retrying.

The CLI passes user text only as arguments to a fixed JXA script through /usr/bin/osascript. It makes no direct network request; the user's Mail app handles provider synchronization. Test fixtures replace osascript only when both test-only environment variables are set.

Who it is for

People and teams using an agent harness on macOS who want to work with their already configured Mail accounts.

Example tasks

List my configured Mail accounts and the mailboxes in one account.
Show the latest ten messages in a selected mailbox.
Search a selected mailbox for a subject or sender.
Read one message by Mail message ID with a bounded body.
Preview a complete draft and approve its exact content.
Preview a complete outgoing message, approve it, send, and check Sent.

Getting started

SKILL.md and the scripts can be read without an account: SKILL.md at https://skillsoutpost.com/agents/desktop-mail-assistant-5b25e540/files?path=SKILL.md, and the list of every file at https://skillsoutpost.com/agents/desktop-mail-assistant-5b25e540/files.

Install the complete package in the skills directory used by your agent harness, keeping scripts/desktop_mail_assistant.py beside SKILL.md. Configure an account in Mail. Run python3 scripts/desktop_mail_assistant.py accounts. When macOS asks, allow the calling terminal or harness to control Mail. You can adjust access in System Settings > Privacy & Security > Automation. The first call may time out while the prompt is open; answer it, then retry a read. For send or draft, provide an exact UTF-8 --body-file, run --dry-run, review the complete preview, and supply its digest with --approve after explicit approval. Test-only DESKTOP_MAIL_FAKE_RESPONSES and DESKTOP_MAIL_FAKE_TRANSPORT_TEST_ACK=1 replace osascript with synthetic fixture responses and must not be used for real mail. Rejects malformed responses, oversized input and invalid UTF-8 explicitly.

Limitations

macOS only; Mail, configured account and Automation permission required. Output limits do not limit mailbox reads. Body files: 400,000 UTF-8 bytes and 100,000 decoded characters; synthetic fixtures: 2,097,152 bytes. Sent correlation is a single immediate scan of the first 100 unsorted entries, matching subject/body, sender substring, sorted To/Cc/Bcc and dateSent >= attempt start minus five seconds. No upper time bound or unique ID: identical messages can match; body normalization, missing Bcc metadata, sync delay or scan position can prevent a match. Correlation does not prove delivery or this specific send. Timeouts after writes are uncertain; inspect Mail before retrying. Version 0.1.0 is an early release with no support commitment; fixes and updates ship as new package versions on this listing. Live sends/drafts pass the full JSON payload as one argument; OS argument-size limits may reject a message below the body-file cap with a clear launch error.

Data practices

The CLI runs fixed JXA through local /usr/bin/osascript; user values are argv, never source. It receives selected account/mailbox/ID/search text for reads or sender, To/Cc/Bcc, subject and full body for send/draft and Sent correlation. Mail uses configured account provider hosts (varying by account) for sync and sends approved sender, recipients, subject and body to the provider and addressed recipients. The CLI itself contacts no host or resolver. Recent/search enumerate the whole selected mailbox; search reads each subject/sender before filtering and sorting. Read enumerates the mailbox and fetches the full selected body before display truncation. Sent correlation reads fields from the first 100 Mail-exposed entries. The CLI reads the selected bounded body file and synthetic fixture, writes no local output or directories, and stores no credentials. Human output escapes untrusted text; the harness may forward stdout. Fake mode needs both test variables, warns, and never launches Mail. Malformed required responses fail explicitly. Automation stdout is captured in memory without a byte cap; display bounds do not bound that capture. Optional subject, sender, dates and account email-address property errors use empty fallbacks; required IDs and account/mailbox selection still fail explicitly.