ten31-database/docs/guides/email.md

paths

paths
backend/email_integration/** backend/digest_mailer.py backend/smtp_send.py

Email capture & drafts (Gmail)

Read this before editing Gmail capture or draft creation.

What it does

• backend/email_integration/ captures Gmail via domain-wide delegation (credentials.py, matcher.py, parser.py, db.py, sync.py, scheduler.py, routes.py) and creates Tier-B in-thread drafts (compose.py). It has its own migrations/.
• Captured email becomes CRM activity through a propose → approve flow — nothing lands on a contact record until a human approves the proposal.

Hard rule

• Agents draft; humans send. Never let an agent send email, post, or contact an LP autonomously. Tier-B compose.py only creates a Gmail draft for human review.

Outbound mail — the daily digest (internal; exempt from "agents draft")

The CRM sends an internal daily activity digest to the fund's own admins. This is the ONE automated send path, and it does not violate the hard rule above: that rule governs outward LP/prospect contact. An internal ops email to the team's own inboxes is a different category. Never extend this path to send to LPs/prospects.

• Transport selector: backend/digest_mailer.py (top-level, not in this package) — send_digest(conn, to_addrs, subject, body) picks Gmail-DWD (preferred) → SMTP (fallback). DWD-impersonation sender = CRM_DIGEST_SENDER env, else the first active admin.
• Gmail-DWD path: gmail_send.py (this package) — reuses credentials.py's DWDCredentialProvider with the gmail.compose scope to call users.messages.send (REST, mirrors compose.py; body is {raw} not the draft's {message:{raw}}). The deployment's DWD grant includes gmail.compose (which authorizes send) but not the narrow gmail.send — so request gmail.compose. Verified live 2026-06-15 (token mint + a real messages.send).
• SMTP fallback: backend/smtp_send.py (top-level) — stdlib smtplib reading SMTP_* env, populated on the box by the Configure Digest SMTP Start9 action (writes /data/secrets/smtp/*; entrypoint exports SMTP_*). A dedicated per-package account, independent of any StartOS system-wide SMTP.
• The admin POST /api/admin/digest/test-email restricts recipients to the active-admin set (not an open relay), and logs send failures rather than echoing them (an auth error can carry a token/credential).

Phase B — the daily digest itself (built)

• Content builder: backend/digest_builder.py (top-level). build_digest(conn, since_iso, until_iso, chat_fn=None) returns {subject, body, has_activity, user_count, email_count, investor_count} and composes two sections:
  • By team member — collect_user_activity: per registered user, both directions (per-mailbox eam.is_sent), with one Spark narrative paragraph per user (ingest/llm.py → Spark Control /v1/chat/completions), never Claude (the digest is deliberately un-anonymized — real LP names + substance stay local). Deterministic count-only fallback if Spark is unreachable (always-send must not fail).
  • By investor — collect_investor_activity: re-pivots the same window across the whole team, deduped per email (a reply to several teammates counts once), direction decided at the email level (outbound if from_email is one of our mailboxes, else inbound). Structured list, no extra Spark calls.
  • Soft-delete filters: email_account_messages.deleted_at IS NULL + users.is_active = 1, and the org/contact name joins drop soft-deleted rows (falling back to the matched address).
• Control is DB-backed, set from the admin panel — digest_builder.load_digest_policy(conn) reads app_settings.digest_policy = {enabled, send_hour}. Precedence: DB row wins (the Settings → Admin toggle + send-time dropdown), else CRM_DIGEST_ENABLED/ CRM_DIGEST_SEND_HOUR seed a first-boot default, else {false, 18}. GET/PATCH /api/admin/digest/policy (admin-only) read/write it. Not a StartOS action — it's an operational toggle, so it lives in-app where it's discoverable and takes effect live.
• Scheduler: backend/email_integration/digest_scheduler.py (co-located with the sync scheduler). One daemon thread, always started; each cycle (60s) re-reads the DB policy and sends once per local day at/after send_hour only when enabled — so toggling in the panel takes effect with no restart. Content window = (last send, now]; cursor (digest_last_sent_at) + once-per-day guard (digest_last_sent_date) live in app_settings, so a missed day rolls into the next digest. Recipients = all active admins.
• On-demand: POST /api/admin/digest/send-now (admin-only) → maybe_send_digest(force=True) builds the real last-24h digest and sends to the admin set regardless of the policy and without touching the daily cursor (a preview never suppresses the scheduled send). Surfaced as a "Send Digest Now" button in Settings → Admin, beside "Send Test Digest Email".
• Decisions (locked): 6 PM default send · always-send (empty days get a "no activity" note) · per-user narrative + by-investor structured section · enable/time controlled in the admin panel. Tests: backend/test_digest_builder.py (per-user + per-investor queries, soft-delete, inbound dedup, two-section compose, fallback, policy resolver, scheduler guards — stubbed LLM + transport).

Email-activity panel (Communications tab) — admin-only

The Communications tab (frontend) is the admin-only search over captured Gmail. The classic manual "Log Communication" form was retired (the Fundraising Grid context menu is the manual-log path). Backed by GET /api/email/activity (routes.py:_h_activity, require_admin server-side) → db.query_email_activity(conn, ...) (the pure, tested query). Filters: investor_id, account_id (mailbox), direction (inbound/outbound), q (free-text over subject/snippet/from). Non-obvious semantics to preserve:

• Matched-only: the panel surfaces ONLY email that links to a known investor/contact (query_email_activity gates on EXISTS email_investor_links). Capture still stores unmatched cold/unknown-sender email (metadata only, see "match-only full storage"), but it is never shown here — the Communications tab is the investor-relationship view, not the raw mailbox.
• Soft-delete lives on the per-mailbox sighting, not the email: emails has no deleted_at. An email is "live" iff it has a sighting with email_account_messages. deleted_at IS NULL — the query gates on EXISTS(... deleted_at IS NULL). (Investor links are email-level and carry no deleted_at, so they need no separate filter.)
• Direction is decided at the email level — outbound if from_email is one of our email_accounts addresses, else inbound — mirroring digest_builder._own_addresses.
• Graveyard investors are hidden from the filter dropdown (CRM-wide graveyard = 0), but their captured email still shows in the list and stays findable by free-text search — it's an audit surface, so history is never hidden, only the picker is.

Tests: backend/email_integration/test_email_activity_panel.py.

Known gap

• Tier-B drafts currently reply to the LP only; reply-all is the next change (see AGENTS.md → Current state).

See also docs/gmail-enablement-runbook.md.