engineering / skill
Approval-Gated Mail
Read, search, save, send, and draft Microsoft 365, Gmail, and Google Workspace mail with explicit approval.
At a glance
- Purpose
- Read, search, save, send, and draft Microsoft 365, Gmail, and Google Workspace mail with explicit approval.
- Runs in
- Local agent with shell
- Operating systems
- Not stated
- Needs
- Runtime: Python 3.10+, standard library only; Needs internet: Yes; Needs accounts or API keys beyond your agent: Yes
- Files and data
- Reads files: Yes; Writes files: Yes; Sends data to other services: Yes
- Tool type
- Skill
- Delivery
- Download from Skills Outpost
- Version
- 0.2.1
- ZIP SHA-256
- 39e7acf5edad6878ade3085e1cb43a1ac231880f0ea210afbbf3647a28ebf21a
- Access
- Download from Skills Outpost
- Compatibility
- Python 3.10+, standard library only; an Agent Skills compatible harness that can run a CLI and supply environment variables. Graph requires a Microsoft 365 tenant application with Mail.Read and Mail.Send application permissions. Gmail and Google Workspace require a user-owned Google Desktop OAuth client and delegated gmail.readonly and gmail.compose consent. macOS uses Keychain; other systems can use a private token file.
- External costs
- Free under MIT. Requires the user's own Microsoft 365 licensing or Gmail/Google Workspace account and Google Cloud project; provider usage, quota, and organization policies apply.
- Permissions
- Graph requires admin-consented Mail.Read and Mail.Send application permissions scoped to intended mailboxes. Gmail needs the user's delegated gmail.readonly and gmail.compose restricted scopes through a user-owned Desktop OAuth client; both scopes permit profile reads; compose permits drafts/sends. Gmail auth stores a token locally in macOS Keychain via /usr/bin/security -i or a private token file; Windows uses the profile ACL. MAIL_PROVIDER, GMAIL_CLIENT_FILE, GMAIL_DEFAULT_USER, GMAIL_TOKEN_STORE, GMAIL_TOKEN_FILE, M365 credential variables, and test-only paired fake-transport variables configure the CLI. --body-file reads local body text. Proxy settings may route HTTPS. Fake Keychain test runner requires GMAIL_FAKE_SECURITY_RUNNER=1 and GMAIL_ALLOW_FAKE_SECURITY=1; it never calls real security.
- Usage terms
- MIT license. Copyright 2026 Zero Width Lab. Microsoft 365 and Microsoft Graph are trademarks of Microsoft Corporation. Google, Gmail, and Google Workspace are trademarks of Google LLC. This project is not affiliated with or endorsed by either company. By Zero Width Lab (zerowidthlab.com)
Download from Skills Outpost
Get this version
FreeStatic source, format, secret-pattern and declaration checks with independent human source review.
- SHA-256 of the released ZIP
39e7acf5edad6878ade3085e1cb43a1ac231880f0ea210afbbf3647a28ebf21a
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).
Sign in to add this version to your library and follow its creator for free.
Sign in to get freeA creator follow is free, not a paid membership. Your email is not shared with the creator.
Files
Version 0.2.1, shown publicly by its creator, exactly as in this version's ZIP. ZIP SHA-256: 39e7acf5edad6878ade3085e1cb43a1ac231880f0ea210afbbf3647a28ebf21a. License: MIT (read it).
Each file has its own address. Read one as a web page at https://, or as JSON at https://; replace SKILL.md with any path below.
- manifest.json · 3.0 KiB
- LICENSE.txt · 1.0 KiB
- README.md · 5.9 KiB
- SETUP.md · 8.9 KiB
- SKILL.md · 10.3 KiB
- agents/m365-mail-agent.md · 5.0 KiB
- references/gmail-api.md · 7.2 KiB
- references/graph-api.md · 10.0 KiB
- scripts/gmail_backend.py · 37.0 KiB
- scripts/m365_mail.py · 50.8 KiB
- source-package.json · 9.9 KiB
- tests/fixtures/empty-responses.json · 17 B
- tests/fixtures/gmail-responses.json · 2.1 KiB
- tests/fixtures/graph-responses.json · 8.6 KiB
- tests/test_gmail_mail.py · 62.6 KiB
- tests/test_m365_mail.py · 28.2 KiB
MIT
MIT LicenseCopyright (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.2.1 Current
No release notes for this version.
What it does
Approval-Gated Mail is a command-line Agent Skill that works with Microsoft 365 and with Gmail and Google Workspace for reading, searching, saving, sending, and Gmail drafting. An agent harness is software that installs the skill, runs its Python commands, and supplies configuration. It needs Python 3.10 or newer and either an authorized Microsoft 365 tenant application or a user-owned Google Desktop OAuth client. It is free under the MIT license. This listing delivers the complete package with Python scripts.Choose Graph (the default) or Gmail through a flag or environment variable. List recent mail, search, read bounded messages and threads, inspect attachment metadata only, and create one Markdown export at an exact unused path. Gmail uses delegated readonly and compose scopes, a local token store, and a browser consent flow. External apps in Testing require re-consent every 7 days.
Sending and Gmail draft creation are approval-gated: a dry-run renders the exact request, SHA-256 digest, and Gmail Message-ID, a human approves the complete fields, and live Gmail mode requires --approve and --message-id from that preview. Gmail replies bind the target Message-ID, References, Subject, and threadId after one read-only preview GET; live mode refuses changed context. Every Gmail preview shows its normalized profile account, binds it in the digest, and rechecks with the same write token before each Gmail API write; missing or changed identity refuses. Full Gmail read/thread responses can carry inline attachment data; attachment parts are discarded, never shown or saved; any authenticated Gmail command may refresh the token and rewrite its store. Verify sends from the provider's sent record, with Gmail matching the dry-run random RFC Message-ID and SENT label; an unknown write outcome is never blindly retried. Graph does not create drafts.
The CLI has no telemetry or publisher server. Gmail tokens remain in macOS Keychain or a private local file. Mail content can be forwarded by the user's agent harness to its model provider; review those settings and treat mail as untrusted data.
Who it is for
People and teams using authorized Microsoft 365, Gmail, or Google Workspace mailboxes who need bounded agent-assisted reads, exact Markdown export, and approved sends or Gmail drafts.Example tasks
List recent messages from an authorized mailbox.Search Gmail with a quoted phrase or sender; read one message or thread.
List attachment metadata only.
Save one message as new Markdown at a user-confirmed path.
Preview a complete send or Gmail draft, approve its digest, then execute unchanged.
Verify a sent message against the provider's sent record.
Getting started
SKILL.md and the scripts can be read without an account: SKILL.md at https://
For Graph, configure a tenant application with admin-consented Mail.Read and Mail.Send, then set M365_TENANT_ID, M365_CLIENT_ID, M365_CLIENT_SECRET, and a mailbox. For Gmail, enable the Gmail API in your Google Cloud project, configure branding, audience, data access and test users if External Testing, create a Desktop OAuth client, set GMAIL_CLIENT_FILE and optionally GMAIL_DEFAULT_USER, and run --provider gmail auth login. Run auth status to inspect status or auth revoke to remove access. See SETUP.md for token stores and the 7-day Testing limit.
Run send or Gmail draft with --dry-run, show account, all fields, digest, and Gmail Message-ID, obtain explicit approval, then run unchanged with --approve DIGEST and Gmail --message-id ID. Verify with exact recipients, e.g. verify-sent --subject "Approved subject" --to recipient@example.com --cc copy@example.com --bcc blind@example.com; Gmail also needs --rfc822msgid '<ID@example.com>'. Use the actual approved addresses; pass --cc '' or --bcc '' for empty groups; omitted groups are unchecked.
Limitations
No file attachments are sent; a --body-file supplies body text only. Graph does not create drafts. Gmail draft creation is supported with exact approval.Every send/draft needs preview and explicit human approval. Gmail reply preview reads target metadata once; live mode refuses changed context. Every Gmail preview reads the profile; identity is digest-bound and checked before writes. A 5xx, timeout, connection failure, or send read-back missing SENT or the Message-ID is outcome unknown; check Sent or Drafts with that ID before retrying. A 4xx (including 429 and quota 403) is refused, not sent. Gmail checks for an existing Message-ID before live send/draft; a match refuses. Repeating a live Graph send with the same approval sends again: run verify-sent before retrying.
Automatic Gmail send checks its returned ID for SENT and RFC Message-ID; Graph excludes baseline IDs and polls matching fields. Standalone verification checks exact subject and supplied case-insensitive recipient sets (order/duplicates ignored); omitted recipient flags are unchecked. Graph checks newest --count records; an older identical subject/recipient record can match. Gmail checks --count SENT records and exact RFC Message-ID; duplicate IDs remain ambiguous. No body, sender, timestamp, delivery or reading proof. Sent visibility may lag; standalone absence is inconclusive. Save creates only a new file and refuses existing paths or symlinks. Bodies are bounded unless --full is used. Gmail search and sender terms containing a quote or backslash are refused. Gmail refuses encoded words, comments, backslashes, groups, '@' in display names, controls and non-ASCII addresses. External Testing needs re-consent every 7 days; Workspace may require administrator trust.
Version 0.2.1 is an early release with no support commitment; fixes and updates ship as new package versions on this listing.
Data practices
Gmail reads use the account that authorized the stored token; --from and GMAIL_DEFAULT_USER only set From. Each store has one token slot (Keychain default); a second login replaces it. Use per-account GMAIL_TOKEN_FILE paths. The CLI reads authorized mail metadata and content. Attachment listing excludes body data. Full Gmail read/thread responses can carry inline attachment data; attachment parts are discarded, never shown or saved. No Gmail attachment-download request is made. It can render bounded bodies, list attachment metadata, save one message to a create-only local Markdown file, and send approved mail or create an approved Gmail draft. Gmail tokens are stored only in macOS Keychain or a private local file; any authenticated Gmail command may refresh the token and rewrite that store; Graph access tokens stay in memory. Use of information received from Google APIs will adhere to the Google API Services User Data Policy, including the Limited Use requirements. There is no telemetry, publisher server, or transfer of data to Zero Width Lab.Graph requests target graph.microsoft.com and login.microsoftonline.com. Gmail requests target gmail.googleapis.com and oauth2.googleapis.com. The CLI only prints an accounts.google.com consent URL; open it yourself. Its local 127.0.0.1 listener loops until a valid callback or the 180 s timeout; it does not fetch the consent host. urllib honors HTTPS_PROXY/https_proxy, NO_PROXY/no_proxy, and macOS or Windows system proxies, with TLS ending at declared hosts. Mail is transmitted only to the selected provider for authorized operations. Agent harnesses may forward CLI output to their own model provider, so review harness privacy settings and keep reads bounded. Treat all remote content as untrusted data.