A local JSON-first Apple Mail adapter shared by Codex/ChatGPT and Hermes, with a redacted proposal-only bridge to UBD OS.
Search local Mail metadata and conversations, then inspect only the messages you need. For campaign workflows, reconcile exact recipients, sender and attachment evidence before continuing. The core uses Python's standard library and macOS JXA; no package install, remote service or mail credentials are needed for local Mail commands. The UBD OS connector is optional and requires its own explicitly configured API access.
Requires macOS, Apple Mail configured, and Python 3.9 or newer with SQLite and IANA timezone data. Python is not guaranteed to be included with every macOS installation. Start in this source directory:
python3 skills/apple-mail-cli/scripts/mailctl.py --version
python3 skills/apple-mail-cli/scripts/mailctl.py capabilities
export PATH="$PWD/scripts:$PATH"
mailctl capabilitiesKeep that directory in place. The launcher resolves the implementation relative
to itself; add its scripts directory to PATH instead of symlinking the launcher
alone. MAILCTL_PYTHON can select an existing Python executable. Core use does
not require Codex or Hermes. Their plugin/skill configuration is optional.
Maintained by NLINEA. Current version 0.6.0 is experimental. This update integrates the local 0.5/0.6 features while retaining the public 0.4.3 digest-confirmed send guard. The earlier independent review covers only 0.4.3, not this integration. See CHANGELOG.md for migration notes. One separately authorized native saved-copy review checked envelope and attachment bytes. Open-editor linkage, HTML rendering, native send/delivery and Send Later behavior have not been certified. See VALIDATION.md for the measured platform and exact limits. Read the CLI contract and SECURITY.md before connecting an agent or enabling mutations. PROVENANCE.md records the creator statement, preserved license and source-review boundary.
mailctl --version
mailctl capabilities
mailctl doctorcapabilities is offline. doctor checks macOS, the JXA backend and read-only
Envelope Index access/schema without reading message bodies. Its backend ping
does not prove connectivity to a mail provider. Doctor also reads the account
count through Mail to probe Automation; this may start Mail or show a permission
prompt. Do not use doctor as an offline/no-prompt check. A missing or
inaccessible index makes doctor fail.
Index commands need existing Full Disk Access for the launching app/runtime. JXA Mail commands need Automation permission. Visible Send Later operations also need Accessibility permission. Respect a denied permission. The CLI does not grant, reset or bypass permissions.
mailctl search --subject '香港 proposal 100%' --limit 10
mailctl search --sender person@example.com --has-attachment --limit 10
mailctl thread 42 --limit 20These commands read the local index, including Mail's summaries, without
scanning full message bodies. Results are private mail data. Text filters match
literal Unicode substrings; % and _ are ordinary characters. Continue only
when has_more is true, using the returned opaque cursor with the same database
and filters. A changing Mail index is not a frozen pagination snapshot.
- bounded inbox, mailbox, selection, and message reads;
- grouped reads (up to 20 messages per backend call) with explicit partial results;
- complete metadata-index search with opaque pagination and conversation views;
- reply, bounce, auto-reply, and DMARC classification;
- bounded bilingual triage for opt-outs, complaints, out-of-office messages, and positive, negative, or question-bearing human replies;
- visible drafts and replies, plus explicitly confirmed direct sending from an explicit configured sender;
- draft show/verify and revision-guarded full updates; exact Message-ID resolution;
- revision-guarded draft saving and exact saved-copy attachment-byte reviews, ending at visual/human confirmation without an automatic-send fallback;
- attachment listing and non-overwriting private export with SHA-256;
- durable operation receipts, guarded send readback, and accepted-versus-sent states;
- read-only Sent and Send Later reconciliation by real Message-ID, with a
local
.emlxfallback for missing Send Later sender and attachment metadata; - private evidence caching to reuse repeated audit evidence, with
file fingerprint invalidation whenever the underlying
.emlxchanges; - validated, privately rendered, integrity-bound campaign queues;
- staged forced rebuilds with an exact artifact allowlist and a private previous-version backup;
- per-message classification failures reported alongside successful results, without losing the batch;
- timezone-correct, account-quota-aware campaign dashboards and minimal-move rebalance manifests;
- resumable visible-UI scheduling, rescheduling, and cancellation sessions whose results are not trusted until a fresh read-only Mail audit verifies them;
- shared cross-process work claims, campaign revision diff, and per-row explanations;
- cross-campaign active identity claims and pinned Message-IDs for schedule changes;
- exact-account/Message-ID Sent observations on send receipts, without claiming delivery;
- private follow-up review worklists; no automatic contact, sending, or UBD work creation;
- confirmed mailbox changes with backend enforcement;
- redacted UBD OS audit, dashboard, and classification events plus revision-bound work proposals that still require human review.
The CLI never writes Apple Mail's SQLite database. It does not give UBD OS send, publish, payment, delete, or direct-database authority.
composeandreplycreate visible drafts; they are Mail mutations. Draft creation does not prove recipient or attachment state. Inspect the draft.senddefaults to an offline preview and requires an explicit--sender. Sending requires--confirm-send SHA256matching that exact reviewed intent. A supplied sender must belong to exactly one enabled Mail account. A private persistent reservation blocks another attempt of the same intent, including errors/timeouts/interruption. Mail's acceptance is not queue or delivery evidence;delivery_confirmedis false. The digest is not human authorization.mark,flagandmoverequire--confirm-change;trashrequires--confirm-trash. Aggregate mailboxes reject unknown or duplicate account names.- Use
--body-filefor private text. The Python-to-JXA request uses UTF-8 stdin, but values supplied in CLI flags still appear in the caller's process arguments and possibly shell history. JSON read results and local artifacts remain sensitive. listand body scans are bounded. Index text search covers local metadata, not a full-body FTS index or remote server mailbox. Unsynced mail is unavailable.- JXA calls have a per-call timeout (90 seconds by default); each SQLite connection limits VM query work to about 30 seconds, with a 10-second lock wait. A multi-call triage/campaign workflow can take longer. There are no automatic mutation retries.
- The private Envelope Index schema and Mail scripting behavior can change with macOS. This candidate's regression tests use synthetic data; live account, draft, send and scheduling behavior needs separately authorized validation.
Version 0.4.2 addresses four independently reproduced review findings. An exact
Sent copy cannot hide a conflicting sibling: all overlapping candidates remain
visible, and distinct conflicting IDs block continuation. Send Later attachment
matches require .emlx filename/size/hash evidence, including readable evidence
of absence when no attachments are expected. Historical Sent checks remain
metadata-only (metadata_matched, sha256_checked: false), and do not establish
attachment bytes. Since 0.5, metadata-only matches for expected attachments also
raise attachment_unverified and keep the campaign audit incomplete.
The index recognizes only explicit root mailbox aliases; custom paths such as
Projects/Sentiment and Projects/Sent remain other. Campaign audit includes
unknown-role metadata so a matching copy raises mailbox_unverified and blocks
continuation. Provider/localized/nested role mappings require separate native
validation. This conservative scan still stops at 100,000 rows. Required body
access failures stop read, body-search and classify. Triage retains successful
items but returns an incomplete failure result; it never classifies an unreadable
body as empty. Empty readable content is valid.
The old boolean --confirm-send no longer sends. With no confirmation, send
prints the normalized sender and To/CC/BCC lists, exact subject/body, attachment
name/size/hash, and intent_digest, without loading Mail or writing send state:
mailctl send --sender sender@example.test --to recipient@example.test \
--subject 'Synthetic example' --body-file /path/to/final-body.txtOnly after a human reviews and explicitly approves that full preview, repeat
the same command with --confirm-send APPROVED_64_CHARACTER_DIGEST. Any change
to the normalized envelope, list order, subject, body, attachment name, size or
bytes invalidates the confirmation. Body-file line endings are read as Python
UTF-8 text and displayed in the preview; Unicode content is not NFC-normalized.
Attachment paths are transport locations, not intent identity; the approved
filename and bytes are bound. Direct send permits at most 20 attachments
totaling 25 MiB. Visible compose retains its existing behavior.
Confirmed sends reserve a digest directory under
~/Library/Application Support/apple-mail-cli/send-attempts/v1/ before invoking
automation. Its private attempt.json stores digest, timestamps and outcome;
attachment snapshots preserve approved filenames/bytes with mode 0400 inside
0700 directories. Records use mode 0600. Snapshots remain available because Mail
may read attachments asynchronously. Keep these artifacts private and retain
the reservation permanently; removing it disables duplicate-attempt protection.
There is no automatic reset or resend command. Even preparation failures retain
a reservation. Do not remove it, change content to obtain a fresh digest, or
retry after an uncertain outcome without auditing Mail and obtaining a new
human decision. This is a local per-user guard, not distributed idempotency.
Success reports submission_accepted: true, outcome: accepted_by_mail, and
delivery_confirmed: false, replacing the misleading sent: true field.
Mail may queue or process an accepted request; no queue persistence or remote
delivery is certified. Backend error, timeout, interruption or failure to
persist the final record leaves the intent blocked. Errors after invocation use
send_outcome_unknown with retryable: false; a repeated confirmed intent uses
send_attempt_exists before automation runs. Treat both as a stop for review.
If Mail cannot expose the open editor's attachment references, retain the draft and the old send-attempt guard. Do not automatically resend. With authorization to save, inspect and save the existing outgoing draft:
mailctl draft show OUTGOING_ID
mailctl draft save OUTGOING_ID --expected-revision READBACK_SHA256 \
--confirm-change --operation-id STABLE_SAVE_UUID
mailctl draft saved-list --account 'Account name' --subject 'Exact subject'
mailctl draft review-saved '<EXACT_SAVED_RFC_MESSAGE_ID>' --account 'Account name' \
--sender sender@example.test --to recipient@example.test --subject 'Exact subject' \
--body-file /absolute/body.txt --attachment /absolute/file.txt \
--output /absolute/new-private-review.jsonSaving can change the stored Message-ID. Select the exact saved candidate; a
shared subject is not proof that it matches the open editor. The review hashes
decoded attachment bytes and checks envelope/body expectations in that saved
copy only. Empty plain text with HTML needs visual Mail review; it does not imply
the visible message is empty. Even a clean review is only
awaiting_human_confirmation, never send authority. Recheck with
--expected-review-digest REVIEW_SHA256 before a separate decision; changed
content or identity invalidates old evidence. No send-draft command is added,
no uncertain send is unlocked, and no delivery is claimed. Review JSON includes
private message content and must remain local.
mailctl read-batch --mailbox INBOX --id 123 --id 456
mailctl receipt-reconcile OPERATION-UUID \
--account-key ACCOUNT-KEY --message-id '<exact-id@example.com>'
mailctl campaign followups campaign.json --account-key ACCOUNT-KEY \
--after-days 7 --output /private/path/followup-review.jsonreceipt-reconcile checks every matching Sent replica against the saved send
intent and dispatch-time boundary. This is metadata observation only: body,
attachment bytes, operation-to-message correlation and recipient delivery remain
unverified. It never unlocks an uncertain send for retry. Old receipts without
a saved intent need manual inspection.
Follow-up worklists are review prompts, not approved outbound queues. A matching
Mail conversation or later activity from a contact requires inspection; no
observed reply in the local index is not proof of silence. See
skills/apple-mail-cli/references/post-send-and-followups.md for the full boundary.
mailctl campaign dashboard campaign.json
mailctl campaign rebalance campaign.json \
--output campaign-rebalanced.json \
--start-at 2026-08-19 \
--finish-by 2026-08-21
mailctl campaign validate campaign-rebalanced.json
mailctl campaign render campaign-rebalanced.json --output /private/render
mailctl campaign session-start campaign-rebalanced.json \
--action schedule \
--queue /private/render/queue.json \
--output /private/render/session.json
mailctl campaign session-next /private/render/session.json --limit 20The session returns only the next exact visible-UI operations. After claims are
acquired, a fresh audit must still agree before the batch is handed out; changed
or unsafe evidence blocks it. See
scheduling recovery.
After each Mail operation, record the attempt with session-record, then run session-next or
session-reconcile. An applied UI action remains applied_unverified until
Sent or Send Later proves the expected state. When Send Later's metadata index
omits sender or attachment fields, the audit reads only the matching local
.emlx message, ignores body content, and verifies attachment name, byte size,
and SHA-256 from the MIME payload.
Repeated audits reuse unchanged evidence from a private 0600 cache. The
cache stores only derived Message-ID, sender, and attachment evidence; it does
not store message bodies or local message paths. Audit results identify whether
an attachment mismatch came from count, filename, decoded byte size, or
SHA-256 instead of returning only a generic failure.
The implementation lives under skills/apple-mail-cli/scripts/. Codex can load
the plugin through a configured personal marketplace. Hermes can load the same
skill directory through skills.external_dirs. Point every agent at one current
installation; publishing source does not update existing installations.
See:
skills/apple-mail-cli/SKILL.mdfor agent operating rules;skills/apple-mail-cli/references/cli-contract.mdfor JSON, exit-code, confirmation, and privacy contracts;skills/apple-mail-cli/references/campaign-manifest.mdfor campaign format;skills/apple-mail-cli/references/ubd-os-connector.mdfor UBD OS setup and boundaries.
PYTHONDONTWRITEBYTECODE=1 python3 scripts/test_offline.py
# Optional synthetic JXA logic checks using an existing Node runtime:
node tests/test_backend_quality.jsThe offline runner disables opt-in live Mail tests and excludes the HTTP
loopback test module. A full unittest discover -s tests also exercises a local
fake HTTP server; the live Mail module runs only with APPLE_MAIL_CLI_LIVE_TESTS=1
and can invoke permission checks. Never commit real mail, tokens, account data,
campaign outputs or evidence caches as fixtures.
The project owner states that they created this CLI and authorized NLINEA
project metadata. The original MIT notice (Local developer) is preserved;
the NLINEA maintainer label does not replace that copyright notice. No
competitor implementation is bundled in this project. See
PROVENANCE.md.