navig-email
Gmail mailroom: rules, watch, labels, stats, digests, drafts — its own navig-email command (Gmail app password over IMAP), and
navig emailinside navig.
Works on its own — its own CLI, no navig required · v0.4.0 · PyPI
On its own (no navig needed)
pip install navig-email
navig-email --help # no navig needed
With navig
pip install navig-email
navig email --help
Commands
| Command | What it does |
|---|---|
navig email attachments save |
Save the message's documents into /inbox/ for paperwork to file (local only). |
navig email brief dismiss |
Not interested: the item is not shown again. |
navig email brief extract |
What the briefing extracts from one email (no model, nothing stored). |
navig email brief items |
Items the briefing has extracted, newest first. |
navig email brief restore |
Bring a newsletter the briefing archived (or moved to Trash) back to the inbox. |
navig email brief run |
Build the briefing and deliver it to Telegram (then archive the newsletters it used). |
navig email brief save |
Keep an item: its source email is never archived or trashed while it is saved. |
navig email brief schedule |
Move the weekly template digest to the briefing: one job that decides itself when it is due. |
navig email connect |
Link a Gmail account: OAuth inside navig, a Gmail app password on its own. |
navig email digest |
Template digest for the period; --llm adds prose through the guarded model door. |
navig email edge deploy |
Deploy the Worker from the plugin's edge/ folder (uses wrangler's own login). |
navig email edge events |
Recent messages the edge handled (metadata only — never bodies). |
navig email edge secrets |
Push the Worker's secrets from navig's own vault/config. Nothing is ever printed. |
navig email edge send |
Send AS support@ |
navig email edge stats |
Counts by alias / tag / day / sender domain for mail that entered at the edge. |
navig email edge status |
Is the Worker up, and does it have Email Sending? |
navig email followup |
Draft follow-ups in the space's style for ledger threads (opt-in model; drafts only). |
navig email imap connect |
Sign in to Gmail over IMAP with an app password, and keep it in the encrypted vault. |
navig email imap disconnect |
Forget the stored app password. |
navig email imap status |
Whether an app password is stored, and where it comes from (never shows it). |
navig email labels ensure |
Create a label (and its parents) if missing; print its id. |
navig email labels list |
Every label with its counts. |
navig email list |
List messages of a folder (newest first). |
navig email organize apply |
Add the new labels to the messages (old labels kept), create new filters. Snapshot written first. |
navig email organize audit |
Labels with counts, equivalent and unused labels, conflicting / forwarding filters (read-only). |
navig email organize preview |
The proposed taxonomy for THIS mailbox, with message counts. Changes nothing. |
navig email organize retire |
After checking apply: take the OLD labels off migrated messages (labels and filters are kept). |
navig email organize rollback |
Undo an apply: take off the labels it added, delete the filters it created. |
navig email outbox approve |
Approve the text you reviewed and schedule it (default: in 15 minutes — time to cancel). |
navig email outbox cancel |
Cancel a queued message. A cancelled job can never be sent. |
navig email outbox confirm-sent |
You found a NEEDS_REVIEW message in Sent: record that it did go out. |
navig email outbox delay |
Move a scheduled send later (or to a given time). |
navig email outbox dispatch |
Run one dispatcher pass now (the daemon does this every ~45 s). |
navig email outbox edit |
Change the text. The approval is dropped — the new version must be approved again. |
navig email outbox history |
The mailroom audit trail: who did what, when (no message bodies). |
navig email outbox list |
Queued, sent and stuck messages, newest first. |
navig email outbox pause |
Emergency stop: hold automatic replies (--all: every send) until resume. |
navig email outbox reopen |
Put a failed or reviewed job back in front of you for approval (never straight to sending). |
navig email outbox resume |
Lift the pause. |
navig email outbox send-now |
Send an approved, scheduled message right now (skips the rest of the wait). |
navig email outbox show |
One job: the exact text, its approval, and its full history. |
navig email policy disable |
Turn a policy off. Replies it already queued will not be sent. |
navig email policy enable |
Turn a policy on for one account. Sending policies need --yes. |
navig email policy list |
Every policy, its scope, and whether it is on. |
navig email policy show |
One policy in full. |
navig email policy test |
What the enabled policies would do with one real message — a dry run, no model call. |
navig email read |
Read one message (or its whole thread), body included. |
navig email replied |
Find every Sent reply to mail that sat in a folder (spam): ledger, corpus, label, stats. |
navig email reply |
Draft a reply to one thread in a chosen style — to Drafts, or the outbox with --queue. |
navig email rules apply |
Run the rules over existing mail (backfill labels). Notifications are NOT sent here. |
navig email rules check |
Validate the rules file; with a message id, show which rules would fire. |
navig email rules list |
The rules the watch applies (space file + enabled daemon rules). |
navig email search |
Search with Gmail's own syntax (spam and trash included). |
navig email send |
Send (or draft) a message — through Gmail, or AS the domain via the Cloudflare edge. |
navig email stats |
Counts for the period (received/sent/spam/unread, per label & rule, top senders, per day). |
navig email status |
Connected account, mailbox size, rules loaded, last watch. |
navig email styles |
The writing styles available to reply (the space's own shadow the built-in ones). |
navig email tag |
Add/remove labels on one message or on a search result. |
navig email watch |
One incremental pass over new mail: rules → labels / Telegram / run. For cron (every 5 min). |
NAVIG Email module — the Gmail side of a mailroom: list/search/read, labels, rules →
incremental watch (labels · Telegram · run:), stats, digests, a spam-reply ledger, and the
daemon's filter→notify triage + scheduled briefings. A first-party navig plugin (free, toggleable).
License: Apache-2.0 · Version: 0.2.0
What it is
navig-email is a first-party NAVIG plugin — it extends NAVIG itself (CLI verbs +
gateway routes), and it is free and toggleable. It reads and writes Gmail through navig's
OAuth connector (navig connector connect gmail); it never carries credentials of its own.
Local-first by design. Tagging, watching, stats, digests, the replied-finder and every
Telegram line are pure logic. A language model is consulted only when a command says so
(digest --llm, followup --draft), the provider is printed, and a non-local provider is
refused unless --allow-cloud is passed.
The mailroom (per space)
A space holds the operator-owned pieces:
<space>/mailroom/rules.yaml rules: match {to, from, from_any, subject_any, body_words, in, has_attachment}
actions: label:<Name> · notify:telegram · star · archive · mark_read · run:navig …
<space>/mailroom/ledger/*.jsonl ledgers (e.g. piratebay.jsonl), idempotent by thread
<space>/mailroom/reports/*.md stats / digest / ledger stats
<space>/.navig/email/state.json the watch cursor (Gmail historyId) + seen ids
navig email status [--space S]
navig email connect # = navig connector connect gmail
navig email list [--folder inbox|spam|sent|all] [-q …] [-n]
navig email search "<gmail query>" [-n] [--json]
navig email read <id> [--thread]
navig email labels list | ensure <Name>
navig email tag (<id> | -q "<query>" --yes) --add <Name> [--remove <Name>]
navig email rules list | check [<id>] | apply -q "<query>" --yes|--dry-run --space S
navig email watch --space S --yes|--dry-run # cron, every 5 min
navig email stats --space S --period day|week|month [--since --until] [--send]
navig email digest --space S --period week|month [--llm --allow-cloud] [--send]
navig email send --to … --subject … [--body …|stdin] [--reply-to <id>] --yes | --draft
navig email replied --space S --in spam --since YYYY-MM-DD [--ledger piratebay] [--label … --apply-labels] [--send]
navig email followup --space S --ledger piratebay --draft [--only-answered] [--model ollama:…] [--allow-cloud]
The edge (Cloudflare Worker on the domain aliases)
edge/ ships cybesis-mailroom, an Email Routing Worker: forward first, then one Telegram
line (per-alias policy, NOTIFY_ALIASES) and one metadata row in D1 — never the body — plus an
X-Cybesis-Tag header on the forwarded copy. Its bearer-protected API is what navig calls:
navig email edge status|stats [--days N --send]|events [-n N] --space S
navig email edge send --to … --subject … --body … [--from legal@cybesis.com] --yes # send AS the domain
navig email send --via cloudflare … # same, from the generic verb
navig email edge deploy [--dry-run] # wrangler deploy from edge/
Config: mailroom.edge.url in the space (.navig/config.yaml); vault label mailroom/edge_token
(= the Worker's EDGE_TOKEN secret). Worker secrets: TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID,
EDGE_TOKEN. Tests: cd edge && node --test test/*.test.mjs.
Install
It ships in the NAVIG monorepo and loads automatically when NAVIG is installed. To add/enable it explicitly:
navig store install navig-email
Development
This package lives in the NAVIG monorepo under plugins/navig-email/. It registers via
the navig.plugins entry-point group; CLI verbs register via navig.commands.
Tests: python -m pytest plugins/navig-email/tests (an in-memory Gmail in tests/fake_gmail.py).
1 maintainer
Metadata
1 maintainer
Release files for navig-email 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| navig_email-0.4.0.tar.gz | 223.7 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| navig_email-0.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 423.5 kB
Security for navig-email 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
