keysat-plans/keysat-smtp-emails.md

Keysat email integration — operator alerts + buyer transactional emails

Context

Today Keysat does NOT send any email. The architecture is deliberately delegation-only: every notable event fires a signed HMAC webhook to whatever endpoints operators have configured (webhook_endpoints table), and the operator's app decides whether to render that as an email, push, in-app banner, Slack DM, etc. The renewal-worker comment in subscriptions.rs makes this explicit: "Keysat does not email buyers itself — operator-driven communication, same as license issuance."

Two cases push against that stance:

1. Operator-facing operational alerts. When something goes wrong INSIDE Keysat (Zaprite auth dies, webhook deliveries to the operator's own endpoint fail 25 times in a row, the master Keysat license is about to expire) — the operator needs to know NOW. Webhooks are the wrong channel because the operator's webhook receiver is itself part of what might be broken, and the operator doesn't have a separate "Keysat health monitor" service waiting to act on these. Email straight from Keysat to the operator, via StartOS SMTP, is the right channel.

2. Buyer-facing emails when Keysat IS the brand. The master Keysat instance (running at keysat.xyz, selling Keysat licenses themselves) is the one operator that legitimately wants Keysat-branded buyer emails — the buyer is buying Keysat, so the email should come from "Keysat support." Most operators (selling Recaps, etc.) should NOT have Keysat send buyer emails — their buyer relationship belongs to their own brand and their existing email pipeline. So this needs to be opt-in per merchant profile, with sensible defaults (off everywhere except the master Keysat profile).

The plan implements both, with clean separation between the two audiences so future operators can opt into one without the other.

Dependency on the merchant-profile model

This plan composes with multi-provider-payment-model.md (the merchant-profile foundation). Per-merchant-profile SMTP override fields already land in that plan's merchant_profiles table (so a Pro/Patron operator running 3 businesses can send each one's buyer emails from a different domain with proper SPF/DKIM/DMARC). The per-business email branding fields (sender_name, reply_to, support_url, brand_color) also live on merchant profiles, not products.

This plan's scope is therefore:

• The notifications module + StartOS SMTP wiring + the Send test email UI (Phase 1 below).
• The operator-alerts module + Tier-1 alert call sites (Phase 2).
• The buyer-email infrastructure + templates + per-profile opt-in flag
  • per-event-type opt-outs (Phase 3).
• Flipping the master Keysat profile's flag to ON (Phase 4).

It assumes the merchant-profile migration has already shipped. If that order flips (we want to ship some email work before merchant-profiles), the schema in this plan would need to be temporarily on products instead, with a follow-up migration to move to merchant_profiles later. That's mechanical but ugly; recommend shipping merchant-profiles first.

High-level shape

• New notifications module (src/notifications/mod.rs) — provider- agnostic interface (send_email(to, subject, body)), implemented against StartOS SMTP. Future-extensible to other channels (Slack, Discord, etc.) if any operator ever asks.
• New operator_alerts module — fires notifications::send_email to the operator's address whenever a tracked system-level condition trips. Always on; no opt-in. Recipient = operator's email from StartOS or a Keysat setting.
• Extension of the existing webhook-dispatch path to ALSO send a buyer email when a per-merchant-profile keysat_sends_buyer_emails = true flag is set AND the event type is in the buyer-relevant set. Default off everywhere except the master Keysat profile (Pro/Patron tier required to flip it on for non-master profiles).
• Template system — markdown/HTML templates per event type, with per-profile override fields already on merchant_profiles (sender name, reply-to, brand color, support URL, custom intro paragraph) so even Keysat-direct emails are sent from the right business with the right branding for each profile. Default templates use the merchant profile's name field.

StartOS SMTP integration

StartOS exposes operator-configured SMTP credentials at the OS level so services don't each have to re-prompt for them. Verify the exact shape before coding (read StartOS 0.4.x SDK docs + look at how an existing StartOS package consumes SMTP — hello-world-startos or nostr-rs-relay likely have examples).

Expected shape based on StartOS 0.4 conventions:

• StartOS exposes SMTP host + port + username + password + from-address via either an env var injected into the package's container OR a read-only API call to the host (start-cli system smtp get or similar).
• The start-sdk's TypeScript layer (in our startos/main.ts) is the right place to read and pass them through — either as env vars set on daemon startup or as a generated config file mounted into /data/.
• Keysat daemon reads them at boot, holds them in AppState::config.smtp, every send_email() call uses them.

Behavior when SMTP isn't configured on the StartOS host: log a WARN ("operator alert dropped: no SMTP configured at StartOS layer; configure in StartOS Settings → Email"), no-op the send, do NOT block the operation that triggered the alert. Keysat's primary job is licensing; email is a notification side-channel.

Behavior when SMTP send fails (auth error, host unreachable): log ERROR with the underlying SMTP error, optionally queue for retry with a small bounded retry budget (3 attempts, exponential backoff). Don't implement a full mailqueue for v1 — failed alerts that retry too many times silently drop, the daemon log is the source of truth. Add a real mailqueue when an operator reports lost alerts.

Operator alerts catalog (always-on, recipient = operator)

Each one is a small tracing-style call site that emits an OperatorAlert event, the operator_alerts module routes to email + audit log. Listed by priority of "operator would want to know within hours."

Tier 1 — operator action required, send immediately

• payment_provider.auth_failed — Zaprite or BTCPay API call returns 401 on N consecutive attempts. Means the API key was rotated / revoked. Body includes which provider, when last-good was, suggested fix ("re-run Connect ").
• subscriptions.auto_charge_consecutively_failing — N (default 3) consecutive renewals failed across the active subscription pool, OR M% (default 25%) of recent renewals failed. Pattern detector, not per-sub. Body includes sample failure reasons.
• webhook_endpoint.failing — a single configured webhook endpoint has hit dead-letter status (failed MAX_ATTEMPTS deliveries). Body includes the endpoint URL, recent error responses, suggested fix.
• master_license.expiring_soon — master Keysat license expires in N days (default 14). Body includes the upgrade URL.
• master_license.expired — master Keysat license has expired. Body flags which features are now locked (per tier-cap matrix), upgrade URL.

Tier 2 — operator should know within a day

• disk_space.low — Keysat-specific (DB growth). StartOS likely also alerts on overall disk, but Keysat can warn earlier if the DB grows unexpectedly. Skip until operator-reported.
• db.backup_overdue — if Keysat tracks last-backup timestamps. Defer.
• update_available — new Keysat version published to registry, opt-in. Useful but not v1.

Tier 3 — informational digest

• weekly_summary — N licenses issued, N revoked, N renewals settled, $X gross revenue this week. Optional, opt-in. Defer.

Throttling. Each alert has a per-alert-kind cooldown (default 6 hours) so a flapping provider doesn't email the operator every minute. Cooldown state persists in a operator_alert_throttle (kind, last_sent_at) table.

Buyer transactional emails (opt-in per merchant profile)

When merchant_profiles.keysat_sends_buyer_emails = 1 for the profile the event's product belongs to, ALSO send a buyer email (in addition to dispatching the webhook). Default 0 everywhere except the master Keysat profile, which defaults to 1 because that's where Keysat IS the brand. Flipping the flag to 1 on a non-default profile is tier-gated to Pro/Patron (Creator-tier operators only have one profile, so the question only matters for them in the master-keysat case; the gate exists for symmetry with the merchant-profile count cap).

Event-to-email mapping

Webhook event	Buyer email
license.issued (one-shot purchase OR first-cycle recurring settle)	Purchase confirmation + license key delivery — receipt, the actual key, download/install instructions link. Critical for buyers who closed the tab before saving the key.
subscription.renewal_pending	Renewal reminder — your next charge is X on Y, link to update card / cancel, link to current subscription state.
subscription.auto_charge_initiated	(Optional, off by default) Auto-charge receipt — "we charged $X to your saved card, here's the receipt." Some operators want this; most don't (transaction email fatigue).
subscription.auto_charge_failed	Payment failed — action needed — your card declined, here's the manual-pay link, your subscription is in a grace period until Y. Most-important buyer email since it's the only path to recover the cycle.
subscription.renewed	Renewal receipt (after settle confirmed). Same content as auto-charge initiated but only sent after confirmation. Pick ONE of this or auto-charge-initiated to avoid double-emails — default to this one.
subscription.lapsed	Subscription ended — grace period expired, license no longer active, link to re-subscribe.
code.redeemed	(Optional, off by default) Discount-code-tied notification, mostly internal.

Template system

• One default template per event type, shipped with the binary in src/notifications/templates/<event>.txt (markdown source rendered to HTML + plain-text alternatives).
• Per-merchant-profile branding overrides already exist on the merchant_profiles table from the multi-provider plan (sender_name, reply_to, support_url, brand_color, support_email, plus the optional SMTP-override block). This plan adds the templating-specific fields (intro_paragraph_md, footer_md, include_license_key, disabled_events) as additional columns on merchant_profiles.
• Default sender_name = profile's name. Default reply_to = profile's support_email (or operator-level fallback if NULL). Default support_url = profile's support_url. So even with zero customization, emails come from "Recaps support@recaps.cc" not "Keysat noreply@keysat" — the profile's identity is the source of truth.
• Templates use a small {{handlebars-style}} variable system. Variables available: buyer_email, license_id (last 8 chars for display), policy_slug, product_name, merchant_profile_name, listed_price
  • currency, next_renewal_at, custom fields from the event payload.
• License-key-delivery template is special: includes the FULL license key (verifiable offline against the operator's pubkey). Operators selling high-value products may want to disable this (deliver out-of-band). Controlled by merchant_profiles.include_license_key (default 1).

Anti-double-email guard

When BOTH a webhook AND a buyer-email fire for the same event, the operator's webhook receiver might ALSO be sending its own email — double inbox spam for the buyer. Mitigations:

• Admin UI surfaces a clear warning when the operator enables both keysat_sends_buyer_emails AND has an active webhook endpoint subscribed to overlapping events: "Recaps's webhook receiver is also subscribed to subscription.renewal_pending. If it's already sending emails, enabling Keysat-direct emails will duplicate buyer mail."
• Don't try to programmatically prevent — that's brittle and Keysat can't know what the operator's webhook code does. Warn + let them decide.

Schema changes

New migration 0021_email_notifications.sql (ships AFTER 0020_merchant_profiles.sql from the multi-provider plan):

PRAGMA foreign_keys = ON;

-- Operator's email (the human running the box). Used for operator
-- alerts. Auto-populated from StartOS account on first boot when
-- available; editable in admin UI Settings page.
INSERT OR IGNORE INTO settings(key, value)
    VALUES ('operator_email', NULL);

-- Per-merchant-profile email flags + customization. Most identity-
-- and-branding fields (sender_name, reply_to, support_url, brand_color,
-- support_email, optional SMTP override block) are already on
-- merchant_profiles from migration 0020. This migration adds the
-- email-specific behavior columns.
ALTER TABLE merchant_profiles
    ADD COLUMN keysat_sends_buyer_emails INTEGER NOT NULL DEFAULT 0
    CHECK (keysat_sends_buyer_emails IN (0, 1));
ALTER TABLE merchant_profiles
    ADD COLUMN intro_paragraph_md TEXT;          -- prepended to every email body
ALTER TABLE merchant_profiles
    ADD COLUMN footer_md TEXT;                   -- replaces default footer
ALTER TABLE merchant_profiles
    ADD COLUMN include_license_key INTEGER NOT NULL DEFAULT 1
    CHECK (include_license_key IN (0, 1));
ALTER TABLE merchant_profiles
    ADD COLUMN disabled_events TEXT;             -- JSON array of event_type strings

-- On the master Keysat instance, flip the default profile's flag to ON
-- (it's the one place buyers are buying Keysat-the-product and the
-- email comes from Keysat). On every other operator's instance, the
-- default profile starts with the flag OFF — they keep using their own
-- email pipeline via webhooks. Operators can flip it ON later
-- (tier-gated for non-default profiles).
--
-- This UPDATE is conditional: only flip if the operator_name resolves
-- to "Keysat" (i.e., this is the master instance). Other operators
-- will see their default profile stay at 0.
UPDATE merchant_profiles
   SET keysat_sends_buyer_emails = 1
 WHERE is_default = 1
   AND name = 'Keysat';

-- Throttle state for operator alerts (one cooldown per alert kind).
CREATE TABLE operator_alert_throttle (
    kind            TEXT PRIMARY KEY,
    last_sent_at    TEXT NOT NULL,
    last_payload    TEXT             -- JSON, last alert body for dedup
);

-- Audit trail of emails sent. Operator-debuggable; bounded by a TTL
-- sweep so it doesn't grow forever.
CREATE TABLE email_log (
    id                  TEXT PRIMARY KEY,
    sent_at             TEXT NOT NULL,
    to_address          TEXT NOT NULL,
    subject             TEXT NOT NULL,
    audience            TEXT NOT NULL,   -- 'operator' | 'buyer'
    merchant_profile_id TEXT,            -- which profile's branding/SMTP was used; NULL for operator alerts
    event_type          TEXT,            -- nullable; some operator alerts not event-driven
    product_id          TEXT,            -- nullable for operator alerts
    invoice_id          TEXT,            -- nullable
    subscription_id     TEXT,            -- nullable
    license_id          TEXT,            -- nullable
    status              TEXT NOT NULL,   -- 'sent' | 'failed' | 'dropped_no_smtp'
    error_message       TEXT,
    CHECK (audience IN ('operator', 'buyer')),
    CHECK (status IN ('sent', 'failed', 'dropped_no_smtp'))
);
CREATE INDEX idx_email_log_sent_at ON email_log(sent_at);
CREATE INDEX idx_email_log_audience ON email_log(audience);

Rust code changes

• New src/notifications/mod.rs:
  • pub struct NotificationsService { default_smtp: SmtpConfig, db: SqlitePool }
  • pub async fn send_email(&self, profile: Option<&MerchantProfile>, to: &str, subject: &str, body_text: &str, body_html: Option<&str>) -> Result<()> — when profile is Some, use the profile's SMTP override fields if present; otherwise fall back to the StartOS-level SMTP. Operator alerts pass None (always uses the default SMTP since they don't belong to any business).
  • Logs to email_log table on every attempt regardless of outcome, tagging which profile's config was used.
  • Implementation: use lettre crate (well-maintained Rust SMTP client) with TLS/STARTTLS support.
• New src/notifications/templates.rs:
  • Template registry mapping event_type → default template.
  • Render function: takes template + variables + per-profile overrides → returns subject, text body, HTML body.
  • Templates embedded via include_str! so no filesystem dependency in container.
• New src/operator_alerts.rs:
  • pub fn alert(state: &AppState, kind: OperatorAlertKind, payload: serde_json::Value)
  • Reads throttle state, sends email (via default SMTP, no profile) if cooldown elapsed, persists last_sent_at.
• New call sites in existing modules:
  • subscriptions.rs — auto_charge_consecutively_failing detector (windowed counter)
  • payment/zaprite/client.rs + payment/btcpay/client.rs — payment_provider.auth_failed on N consecutive 401s
  • webhooks.rs (delivery worker) — webhook_endpoint.failing when an endpoint hits dead-letter
  • tier.rs — master_license.expiring_soon / master_license.expired daily check
• Extend webhooks::dispatch to also call notifications when the product's merchant_profile.keysat_sends_buyer_emails = 1 AND the event is buyer-relevant. The notification call passes the profile, so per-profile SMTP / branding applies.
• AppState::config gains an smtp: Option<SmtpConfig> field (default StartOS-level SMTP), populated at startup.
• startos/main.ts (TypeScript wrapper): read StartOS SMTP config and pass it to the daemon as env vars or a generated config file.

Admin UI changes (in web/index.html)

• Settings page → new "Notifications" disclosure (operator-level):
  • Operator email field (auto-populated from StartOS, editable)
  • Default SMTP status (connected/error/not configured), inherited from StartOS
  • "Send test email to operator" button to verify the default SMTP path
  • List of recent emails sent (paginated, from email_log), filterable by audience (operator vs buyer) and by merchant profile
• Merchant Profile edit page (already exists from multi-provider plan) → "Buyer emails" disclosure:
  • Toggle: "Have Keysat send buyer emails for this merchant profile" (default off; default on for the master Keysat profile only)
  • Per-event opt-outs (checkboxes for each buyer-event row in the Event-to-email mapping above)
  • "Intro paragraph" + "Footer" markdown fields
  • "Include license key in confirmation email" checkbox
  • "Test send" button rendering one of the templates against the profile's SMTP config + branding
  • Inline warning if any active webhook is subscribed to overlapping events (anti-double-email guard from above)
• (Branding + SMTP-override fields live on the existing Merchant Profile edit page sections, not duplicated here — they're owned by the multi-provider plan.)

Sequencing

Single cycle if it's all you ship. Otherwise consider this order:

1. Phase 1 — StartOS SMTP wiring + notifications module (:NN+1). No call sites yet, just the plumbing + a Send test email button on the Settings page so operators can validate the path. Low risk, immediately testable.
2. Phase 2 — Operator alerts (:NN+2). Wire in the 4-5 Tier-1 alerts. No buyer-facing changes. Operators get immediate value.
3. Phase 3 — Buyer emails infrastructure (:NN+3). Schema + template engine + admin UI for the per-merchant-profile config. Default everything off — no behavior change yet.
4. Phase 4 — Buyer email triggers (:NN+4). Wire the webhook- dispatch path to also send emails when configured. Default ON for the master Keysat profile, OFF everywhere else. This is the user-visible cut.

Phases can be one release each (4 routine bumps) or rolled together if they're shipped as a coherent feature.

Verification

1. Test send from Settings page — verifies StartOS SMTP integration end-to-end without needing a real event to trigger.
2. Operator alert test: revoke the Zaprite API key on Zaprite's dashboard, trigger any purchase attempt → expect a Tier-1 email within the throttle window naming the provider and suggesting the fix.
3. Buyer email test (master Keysat): buy a Keysat self-license on the master keysat.xyz instance (its profile has the flag = 1 from the migration) → expect a Keysat-branded confirmation email with the license key, sent from the Keysat profile's SMTP config + branding.
4. Buyer email test (Recaps operator path): on an operator instance with a Recaps merchant profile (flag = 0), buy a Recaps license → confirm Keysat sends NO buyer email; only the webhook fires for Recaps's receiver to handle.
5. Per-profile SMTP test (Pro/Patron): on a Pro-tier operator instance, create two profiles, each with its own SMTP override (different sender domains). Buy a product on each. Confirm each buyer email arrives from the correct sender domain with the correct profile branding (verifies the per-profile SMTP routing).
6. Anti-double-email warning: enable merchant_profiles.keysat_sends_buyer_emails on a profile that has a webhook subscribed to overlapping events → confirm the admin UI shows the warning.
7. Throttle test: trigger the same operator alert twice in quick succession → confirm only one email sent, second one suppressed, audit log shows the cooldown.

Out of scope for this work — future considerations

• Other notification channels (Slack, Discord, push). Email is the highest-leverage channel and matches StartOS's existing infrastructure. Other channels are a natural extension if any operator asks.
• Operator-side email-domain authentication setup (DKIM/SPF configuration help). Keysat consumes whatever StartOS gives it; operators handle their own deliverability hygiene. We can link to a docs page from the Settings UI.
• HTML email template editor in the admin UI. Operators get markdown + a small variable set; if they want full template control, they use webhooks + their own pipeline. Adding a WYSIWYG editor is a much bigger UI investment.
• Per-customer email preferences (let buyers opt out of renewal reminders). Not a v1 feature — buyers can ignore emails. Build when someone hits GDPR / CAN-SPAM compliance edge cases at scale.
• Multi-language email templates. Defer; templates ship English-only.
• Transactional email service integrations (SendGrid/Postmark/etc. in addition to or instead of StartOS SMTP). StartOS SMTP is the right default — it's already configured and the operator pays nothing extra. Other providers are a deferred option.

How this composes with the multi-provider / merchant-profile plan

The merchant-profile plan ships first (migration 0020) and creates the merchant_profiles table along with the identity, branding, and optional-SMTP-override fields. This plan layers on top (migration 0021) adding the email-behavior columns (keysat_sends_buyer_emails, intro_paragraph_md, footer_md, include_license_key, disabled_events) plus the operator-level operator_email setting, the operator_alert_throttle table, and the email_log table.

Admin UI work is symmetric: the multi-provider plan owns the Merchant Profile edit page's identity, branding, and providers sections. This plan adds a "Buyer emails" disclosure on the same page.

No code conflict — the merchant-profile plan touches payment routing, this plan touches the dispatch tail. They compose cleanly. Shipping them in sequence (rather than as one combined cut) keeps each cycle's scope reviewable.