feat(email): the report, invites, resets and test sends go through the outbox; only it talks SMTP (#5508)

#5508 "Every other email through the outbox: weekly report, invites,
password resets, and the test buttons" (milestone 501).

- outbox.send_each queues one email per reader (claimed, so the sender
  doesn't take it too) and tries them at once, for a page that answers
  with what happened; outbox.said words the result. attempt takes a cfg
  for a test of the form's unsaved settings and returns the settled rows.
- Weekly report (scheduled and Send now) and invites: queued, tried at
  once; one the server couldn't take yet is retried for an hour. An invite
  that didn't go shows its link with the reason, as before.
- Password reset: queued in the reset link's own transaction; the sender
  delivers it on its next tick.
- Settings -> Notifications test email and a rule's Send test: queued and
  recorded with retry=False, tried once (System 156 ruling).
- Removed mail.send, notifications._send_email and _smtp_send_sync;
  dispatch_notifications is webhook only. A guard asserts only the outbox
  (and smtp_open itself) opens an SMTP connection, with a self-test.

Also fixes run 8941 (#5507's integration test): its Also-send-to
addresses were "@test", which is_real_address rightly drops; they are
example.com now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

steward/core/outbox.py

@@ -33,7 +33,7 @@ import logging
 import smtplib
 from datetime import datetime, timedelta, timezone
 from email.message import EmailMessage
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Callable
 
 from sqlalchemy import insert, or_, select, text, update
 
@@ -104,18 +104,22 @@ def reason(exc: BaseException) -> str:
 
 def enqueue(db, *, kind: str, to: "Recipient | str", subject: str | None = None,
             text: str | None = None, html: str | None = None,
-            send_after: datetime | None = None, retry: bool = True,
+            send_after: datetime | None = None, retry: bool = True, claimed: bool = False,
             now: datetime | None = None) -> EmailOutbox:
     """Add one email to the queue in `db`'s transaction (the caller commits).
     `send_after` holds it until then (an alert burst, #5507); otherwise it is
-    due at once. `to` is a mail.Recipient, or a bare address read in UTC."""
+    due at once. `claimed` marks it as being sent by the caller, who will
+    `attempt` it right after committing, so the sender doesn't take it too;
+    a claim the caller never settles goes back to the queue (STALE_CLAIM_S).
+    `to` is a mail.Recipient, or a bare address read in UTC."""
     now = now or datetime.now(timezone.utc)
     address, tz, show_utc = (to, "UTC", False) if isinstance(to, str) else \
         (to.address, getattr(to.tz, "key", None) or "UTC", to.show_utc)
     row = EmailOutbox(kind=kind, recipient=address, tz=tz, show_utc=show_utc,
                       subject=subject, text=text, html=html, retry=retry, created_at=now,
-                      state="held" if send_after else "pending", send_after=send_after,
-                      next_attempt_at=send_after or now)
+                      state="held" if send_after else "sending" if claimed else "pending",
+                      send_after=send_after, next_attempt_at=send_after or now,
+                      claimed_at=now if claimed else None)
     db.add(row)
     return row
 
@@ -219,14 +223,18 @@ async def write_held(app: "Quart", db, row: EmailOutbox) -> None:
     row.subject, row.text, row.html = alert_words(app.config.get("SMTP", {}), alerts, to)
 
 
-async def attempt(app: "Quart", ids: list[str], now: datetime | None = None) -> dict[str, str]:
+async def attempt(app: "Quart", ids: list[str], now: datetime | None = None,
+                  cfg: dict | None = None) -> dict[str, EmailOutbox]:
     """Try to send the claimed rows `ids` once, and settle each. The words
     are written and kept first, so a retry sends the same email; no session
-    is held while the mail server is talked to. Returns {id: state after}."""
+    is held while the mail server is talked to. `cfg` replaces the saved mail
+    settings for this one try (a test of the form's unsaved values; such a
+    row has retry=False, so nothing later needs them). Returns {id: row}
+    as settled."""
     from steward.core.mail import message
     if not ids:
         return {}
-    cfg = app.config.get("SMTP", {})
+    cfg = cfg if cfg is not None else app.config.get("SMTP", {})
     outcomes: dict[str, BaseException | None] = {}
     sendable: list[tuple[str, EmailMessage]] = []
     async with app.db_sessionmaker() as db:
@@ -257,7 +265,7 @@ async def attempt(app: "Quart", ids: list[str], now: datetime | None = None) ->
                 if row.state == "failed":
                     logger.warning("email %s to %s failed: %s", row.kind, row.recipient, row.last_error)
             await after_settle(db, rows)
-        return {row.id: row.state for row in rows}
+        return {row.id: row for row in rows}
 
 
 async def after_settle(db, rows: list[EmailOutbox]) -> None:
@@ -315,6 +323,36 @@ async def send_due(app: "Quart") -> None:
     now = datetime.now(timezone.utc)
     ids = await claim_due(app, now)
     if ids:
-        states = await attempt(app, ids, now)
-        logger.info("email outbox: %d tried, %d sent", len(states),
-                    sum(1 for s in states.values() if s == "sent"))
+        rows = await attempt(app, ids, now)
+        logger.info("email outbox: %d tried, %d sent", len(rows),
+                    sum(1 for r in rows.values() if r.state == "sent"))
+
+
+async def send_each(app: "Quart", kind: str, to: list, words: Callable[..., tuple],
+                    *, retry: bool = True, cfg: dict | None = None) -> list[EmailOutbox]:
+    """Queue one email per reader in `to` (mail.Recipient or address),
+    written by `words(reader)` -> (subject, text, html), and try them at
+    once, for a page that answers with what happened (see `said`). Returns
+    the rows as settled: a temporary failure is left pending for the sender
+    to retry, unless retry=False (a test). `cfg` as for `attempt`."""
+    async with app.db_sessionmaker() as db:
+        async with db.begin():
+            rows = [enqueue(db, kind=kind, to=r, subject=s, text=t, html=h, retry=retry, claimed=True)
+                    for r in to for s, t, h in [words(r)]]
+            await db.flush()
+            ids = [r.id for r in rows]
+    done = await attempt(app, ids, cfg=cfg)
+    return [done[i] for i in ids if i in done]
+
+
+def said(rows: list[EmailOutbox]) -> tuple[bool, str]:
+    """(all sent, what happened) for rows just tried: who it went to, who
+    refused and why, and who Steward is still trying."""
+    sent = [r.recipient for r in rows if r.state == "sent"]
+    failed = [f"{r.recipient}: {r.last_error}" for r in rows if r.state == "failed"]
+    later = [f"{r.recipient} ({r.last_error})" for r in rows if r.state == "pending"]
+    parts = ([f"Sent to {', '.join(sent)}."] if sent else []) + \
+        ([f"Not sent to {'; '.join(failed)}."] if failed else []) + \
+        ([f"Not sent yet to {'; '.join(later)}; Steward will try again for up to an hour."]
+         if later else [])
+    return bool(rows) and not failed and not later, " ".join(parts)