Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/MAIL-01.md
T

5.2 KiB

MAIL-01 · Mailjet-Willkommensmail nach Signup zuverlässig zustellen

Typ Launch-Fix · Transactional Mail
Owner Raffael
Phase Pilot-Härtung
Cycle/Fenster gestartet 2026-08-01
Status Done
Plane HIVEGRID-237

Abhängigkeiten & Parallelität

  • Blocked by: kein technischer Blocker. EXT-02 bestätigt Domain, Sender, SPF und DKIM; Signup und Transactional-Mail-Queue sind bereits produktiv verdrahtet.
  • Blocks: zuverlässige Welcome-Experience für neue Pilot-Tenants.
  • Abhängigkeitsschutz: Sender, React-Email-Template, Queue, Retry, Signup-Idempotenz und Marketingversand bleiben unverändert.

Was / Warum

Der direkte Staging-Signup erzeugt für die Willkommensmail den stabilen Key mail:signup-welcome:<tenant>:<creation-request-key>. Dieser Key ist im echten Fall 93 Zeichen lang. Der Mailjet-Sandbox-Proof mit dem exakten Staging-Konto bestätigte die Grenze: 64 Zeichen werden akzeptiert; ab 65 Zeichen antwortet Mailjet mit HTTP 400 / mj-0006 für CustomID.

Der Provider-Adapter nahm fälschlich 100 Zeichen an. Lange Replay-Keys werden deshalb deterministisch auf eine höchstens 64 Zeichen lange Korrelation abgebildet. Kurze IDs bleiben für den Betrieb lesbar. Exakte Retries müssen dieselbe ID, verschiedene lange Keys praktisch kollisionsfrei verschiedene IDs erhalten.

Nicht im Scope

  • Kein neues Mail-Template, kein Providerwechsel und kein Marketingversand.
  • Keine Änderung an Signup-, Queue-, Retry- oder Delivery-Idempotenz.
  • Keine Live-/Produktionsmail und keine Änderung an Mailjet-Secrets.

Definition of Done

  • CustomID ist für jede Eingabe höchstens 64 Zeichen lang; Werte bis zur Grenze bleiben bytegleich.
  • Lange Keys werden deterministisch und kollisionsresistent kompaktiert; der rohe lange Key verlässt den Adapter nicht im Payload.
  • Fokus-Tests decken 64/65+, exaktes Replay und verschiedene lange Keys ab.
  • Typecheck, Lint, vollständige Testsuite und Package-/Security-Gates sind grün.
  • PR-CI, normaler Merge und Staging-Deploy sind grün; ein frischer Test-Signup belegt die Welcome-Zustellung und das Rendering per Screenshot.

MAIL-01: 5/5 DoD = 100 % done. Kein selbst machbarer Punkt offen.

Technische Bausteine

  • packages/mail/src/mailjet.ts
  • packages/mail/src/mailjet.test.ts
  • bestehender mail:signup-welcome-Outbox-/Queue-Vertrag
  • CR-012 in docs/CHANGE-REQUESTS.md

Rollback

Reiner Code-Rollback des Provider-Normalizers. Es gibt keine DB-Migration und keinen persistierten Vertragswechsel. Bereits kompaktierte IDs sind nur Provider-Korrelationen; Queue- und Delivery-Idempotenz bleiben an den unveränderten vollständigen Replay-Key gebunden.

Umsetzungs-Notiz

2026-08-01 · Diagnose und Implementierung gestartet

  • Mailjet-Sandbox-Proof: 32, 50 und 64 Zeichen HTTP 200; 65, 80, 93 und 100 Zeichen HTTP 400 / mj-0006 für CustomID.
  • Sender noreply@hivegrid.de und Wildcard-Domain sind im exakten Staging-Konto aktiv; SPF/DKIM sind grün. Der Fehler liegt nicht am Sender.
  • Der Adapter bewahrt IDs bis einschließlich 64 Zeichen bytegleich. Längere IDs erhalten hivegrid-id: plus 52 Hex-Zeichen SHA-256; gleiche Keys bleiben replay-stabil, verschiedene lange Keys erhalten verschiedene Korrelationen.
  • Lokaler Proof: 99/99 Mail-Package-Tests, Package-Typecheck und fokussiertes ESLint grün; anschließend Repo-Typecheck, Repo-Lint und 8.207/8.207 Tests in 1.168 Testdateien grün (60 bewusst übersprungen).
  • Der bestehende Transactional-Mail-Baseline-Gate verwies noch auf die längst entfernte mailersend.test.ts und scannte historische Doku nach Postmark. Er läuft jetzt gegen Mailjet plus den kanonischen Runtime-Removed-Module- Scanner; 3.834 Runtime-Dateien sind frei von verbotenen Provider-Resten und der vollständige Baseline-Gate ist grün.

MAIL-01: 4/5 DoD = 80 % done. Offen: PR-CI, normaler Merge, Staging-Deploy und Welcome-Zustellproof; kein externer Blocker.

2026-08-01 · Staging-Zustellung und Rendering abgenommen

  • Commit 71ea96992 bestand die vollständigen Gates, wurde über PR #327 normal gemergt und war Bestandteil der grünen Staging-Revision 137358736 aus Deploy 11669.
  • Der frische deutsche BILL-14-Signup erzeugte exakt eine Mail. Das reale Testpostfach erhielt am 2026-08-01 um 12:55:44 UTC den Betreff „Willkommen bei HiveGrid, Pilot!“; HTML-Rendering und CTA waren vorhanden.
  • Screenshot 58-final-welcome-mail-delivered.png im finalen Desktop-UAT- Ordner belegt die tatsächlich zugestellte und gerenderte Mail. Es wurden keine Production-Mail und keine Mailjet-Secret-Änderung ausgelöst.
  • Locale-/Footer-, Plaintext- und Branding-Härtung bleiben bewusst außerhalb des engen CustomID-Fix-Scope und werden getrennt nachgezogen.

MAIL-01: 5/5 DoD = 100 % done. Kein selbst machbarer Punkt offen.