Kampagnen-Interna

Diese Seite ist die Entwicklerreferenz für den Kampagnen-Versandpfad im Convex-Backend — was zwischen dem Klick auf Senden und dem Postfach einer empfangenden Person passiert. Sie behandelt die beiden Lebenszyklus-Zustandsmaschinen, das Versand-Pre-Flight-Gate, die Orchestrator-Pipeline, die emailSends-Datensätze pro Empfänger und die ratenbegrenzten Workpools. Die anwenderseitige Anleitung finden Sie unter Kampagne senden & überwachen; wie die Zielgruppe in Empfänger aufgelöst wird, steht unter Zielgruppen-Interna.

Zustandsmaschine des Kampagnen-Lebenszyklus

Das Feld status der Kampagne wird von genau einem Modul geschrieben — apps/api/convex/campaigns/lifecycle.ts. Dessen öffentliche transition-Mutation ist der einzige Schreiber von campaigns.status und der Begleitfelder, die sie zusammen damit patcht (sentAt, cancelledAt, scheduledAt, contentBlockReason sowie der Stats-Null-Block beim Versand). Ein direktes ctx.db.patch von status an anderer Stelle ist ein Schichtverstoß.

Die sechs Status

Erlaubte Kanten

Der Reducer lehnt jeden Übergang ab, der nicht in LEGAL_EDGES steht. Es wird keine Exception geworfen — ein unzulässiger Aufruf gibt { ok: false, reason: 'illegal_edge' } zurück, und ein Übergang aus einem terminalen Status gibt reason: 'terminal' zurück. Die Aufrufer übersetzen das Ergebnis in eine Antwort an die Nutzerin.

Eine Selbstschleife (from === to) ist idempotent: Sie schreibt eine Audit-Log-Zeile, gibt applied: 'recorded' zurück und erzeugt kein Patch, keinen Scheduler-Hop und kein PostHog-Event. Genau das macht einen erneut ausgelösten Scheduler-Tick unbedenklich.

Effekte

Der Reducer ist pur: Aus der geladenen Kampagne, der typisierten Eingabe und einer userId gibt er ein patch plus eine Liste von effects zurück. Ein separater Runner wendet sie der Reihe nach an, atomar mit dem Patch der Zeile. Es gibt vier Effektarten:

Das Argument userId unterscheidet nutzergetriebene von systemseitigen Übergängen. Nutzerseitige Mutationen übergeben session.userId; interne Aufrufer übergeben ein Tag 'system:<source>' (z. B. 'system:scheduler_tick', 'system:content_scan', 'system:orchestrator', 'system:send_completion'). Das Audit-Log hält das Tag wortgetreu fest, und der track_event-Effekt wird für jeden Aufrufer mit system:-Präfix unterdrückt — Hintergrundübergänge verschmutzen PostHog also nie.

sent erreichen: Batch-Abschluss

→ sent wird nicht von der Nutzerin ausgelöst. Jeder Workpool-Callback pro Send bewegt seine eigene emailSends-Zeile weiter, aber die Kampagne selbst schließt erst ab, wenn ihr letzter eingereihter Send die Queue verlässt. tryCompleteCampaign (im selben Modul) ist der gemeinsame Wächter, der von zwei Stellen aufgerufen wird:

• reconcileCampaignCompletion — der Einstiegspunkt pro Send, aufgerufen aus dem Workpool-Completion-Callback, nachdem jeder Send einen terminalen Status erreicht hat. Ein günstiger No-Op, bis die Kampagne wirklich fertig ist.
• reconcileSendingCampaigns — ein Sicherheitsnetz-Cron (process scheduled campaigns läuft jede Minute; dieser Sweep läuft ebenfalls jede Minute als reconcile sending campaigns), der jede noch in sending befindliche Kampagne abgleicht. Er fängt Callbacks ab, die fehlgeschlagen sind, oder finale Sends, die statt vom Workpool durch einen Provider-Webhook überführt wurden.

tryCompleteCampaign wechselt nur dann zu sent, wenn alles davon gilt: Der Status ist sending; der gecheckpointete Send-Walker hat das Streamen beendet (keine campaignSendJobs-Zeile mehr in Phase resolving); ein etwaiger A/B-Test hat winner_selected erreicht (sonst würde der Rest-Versand der zweiten Welle übersprungen); mindestens eine emailSends-Zeile existiert; und keine emailSends-Zeile ist noch queued. queued ist der einzige nicht terminale Send-Status, sein Fehlen bedeutet also, dass die Kampagne fertig ist.

A/B-Test-Lebenszyklus und die Rest-Versand-Garantie

Die Spalte abTestStatus hat ihre eigene Maschine in apps/api/convex/campaigns/abTestLifecycle.ts — dieselbe Zeile, andere Spalte, eigener Graph. Ihre transition-Mutation ist der einzige Schreiber von abTestStatus und dessen Begleitfeldern (abTestConfig, abWinner, abWinnerSelectedAt sowie der Block zum Zurücksetzen der Variantenstatistiken beim Deaktivieren).

Zwei Effekte garantieren, dass die zurückgehaltene Zielgruppe nie verwaist:

• schedule_auto_winner löst bei → testing aus, wenn winnerCriteria nicht manual ist und testDuration (Stunden) gesetzt ist. Es plant campaigns.abTest.autoDeclareWinner nach dem Testfenster ein. Ohne diesen Effekt würde eine open_rate- / click_rate-Kampagne (der Wizard-Standard) für immer in testing sitzen und die 40–60 % Restzielgruppe nie versendet. Manuelle Kriterien setzen stattdessen darauf, dass die Nutzerin einen „Gewinner wählen"-Button klickt, den die Report-Seite nur bei manual anzeigt.
• schedule_winner_remainder löst bei → winner_selected aus. Es plant campaigns.send.sendCampaignWinnerToRemainder (den Orchestrator der zweiten Phase, siehe unten) ein, um den Inhalt der Siegervariante an alle Zurückgehaltenen auszuliefern.

Versand-Pre-Flight-Validierung

Bevor irgendein Aufrufer eine Kampagne nach scheduled oder sending überführt, führt er das Pre-Flight in apps/api/convex/campaigns/preflight.ts aus. Der Lebenszyklus-Reducer vertraut seiner Eingabe — er validiert die Versandbereitschaft nicht erneut —, sodass das Pre-Flight das eine Gate ist, das sich die vier Versand-/Planungs-Einstiegspunkte (und der Orchestrator zum Auslösezeitpunkt) teilen.

validateReadyToSend gibt eine PreflightResult-Union zurück; die erste fehlschlagende Prüfung gewinnt. Die Prüfungen in ihrer Reihenfolge:

Die interne Query validateReadyToSendQuery kapselt dieselbe Logik, damit der Orchestrator das Pre-Flight zum Auslösezeitpunkt erneut ausführen kann — und so Zustände abfängt, die zwischen dem ursprünglichen schedule-Aufruf und dem Scheduler-Tick abgedriftet sind (Organisation gesperrt, Template gelöscht, Domain-Verifizierung abgelaufen).

Der Versand-Orchestrator

campaigns.send.startCampaignSend (apps/api/convex/campaigns/send.ts) ist die einzige laufende Action, die eine Kampagne von scheduled | sending durch die gesamte Vorbereitungs-Pipeline führt. Sie wird von drei Produzenten ausgelöst: dem Cron-Tick processScheduledCampaigns, dem Effekt schedule_campaign_send_orchestrator des Lebenszyklus und einer direkten Neuplanung in campaigns/scheduling.ts. Sie ist der einzige Schreiber von emailSends.abVariant und der einzige Aufrufer von enqueueCampaignEmails in der ersten Phase.

Details zum A/B-Fanout

resolveAbFanout (campaigns/sendVariantSplit.ts) liefert nur dann ein Fanout, wenn für die Kampagne isABTest gilt, abTestStatus === 'testing' ist und eine Konfiguration vorliegt — eine Kampagne in winner_selected oder pending splittet in der ersten Phase also nie. Der Split ist ein deterministischer FNV-1a-Hash von (campaignId:contactId) (hashFraction), verglichen mit testFraction = 2 × splitPercentage / 100: h < testFraction ist die Testkohorte (per variantForHash am Kohorten-Mittelpunkt in A/B unterteilt), und h >= testFraction ist der zurückgehaltene Rest. Empfänger strömen Seite für Seite durch den gecheckpointeten Send-Walker (resolveCampaignPage) — sie werden nie gemischt oder vollständig materialisiert.

Der zurückgehaltene Rest wird in der ersten Phase nicht versendet. Nachdem ein Gewinner feststeht, löst die Action der zweiten Phase, campaigns.send.sendCampaignWinnerToRemainder, die Zielgruppe erneut auf, schließt jeden Kontakt aus, der für diese Kampagne bereits eine emailSends-Zeile hat (das deckt die Testkohorte ab und schützt vor Doppelversand), und reiht den Inhalt der Siegervariante für den Rest ein. Beide Phasen teilen sich den Helfer enqueueVariantBatch pro Variante — die einzige Stelle, die emailSends-Zeilen anlegt und enqueueCampaignEmails einplant.

emailSends-Datensätze und die „ever-reached"-Statistiksemantik

Jeder Empfänger einer Kampagne erhält eine emailSends-Zeile (apps/api/convex/schema/campaigns.ts). E-Mail-Adresse, Vor- und Nachname des Kontakts werden zum Versandzeitpunkt gesnapshottet und nie aktualisiert — die Zeile ist der Audit-Trail dessen, was tatsächlich gesendet wurde, nicht eine Live-Ansicht des Kontakts. status ist ein einzelnes Feld mit acht Werten; queued ist der einzige nicht terminale.

Statusschreibungen laufen über einen Schreiber — internal.delivery.sendLifecycle.transition mit einem SendRef { kind: 'campaign', id }. Die alten Mutationen pro Ereignis in delivery/sends.ts (dem Mutationsmodul der emailSends-Tabelle) wurden entfernt; dieses Modul liest nur noch, legt an (einzeln über create und gebündelt über createBatch) und löscht.

getStatsByCampaign und die anderen Aggregat-Reads pro Send begrenzen ihre Scans (typischerweise take(10_000)); Kampagnen, die größer sind, sollten sich auf die denormalisierten stats*-Zähler an der Kampagnenzeile stützen, die der Send-Lebenszyklus pro Empfänger hochzählt.

Kampagnen- vs. Transaktions-Workpools und Rate Limiting

E-Mail-Sends laufen über zwei getrennte Convex-Workpools, definiert in apps/api/convex/delivery/workpool.ts:

Zwei Pools verhindern, dass Transaktionsmail hinter einer langen Kampagnen-Queue blockiert wird. Die kombinierten ~50/Sek. bleiben mit Sicherheitsmarge unter den Rate-Obergrenzen der Provider. Beide Pools setzen retryActionsByDefault, aber maxAttempts: 1 — genau ein Worker-Lauf und kein Retry auf Pool-Ebene. Die versandseitige Retry-Schleife gehört ausschließlich dem Dispatch-Helfer (lib/sendProviders/dispatch.ts, ADR-0020); ein Pool-Retry würde den ganzen Worker erneut ausführen und Doppelversand riskieren. Die Felder für 1 s Basis und Faktor 2 im Backoff existieren, werden bei maxAttempts: 1 aber nie ausgeübt.

enqueueVariantBatch des Orchestrators plant enqueueCampaignEmails ein, das campaignEmailPool.enqueueAction einmal pro Empfänger aufruft und dabei auf internal.delivery.worker.sendSingleEmail zielt. Jedes Enqueue verdrahtet den Completion-Callback auf internal.delivery.sendCompletion.completeSend und trägt eine typisierte sendRef im Workpool-Kontext, damit das Completion-Modul Worker-Ergebnisse einheitlich in Send-Lebenszyklus-Übergänge übersetzen kann. Standard-Sends werden sofort in Blöcken zu 50 eingeplant; zeitzonenbewusste Sends (useRecipientTimezone plus scheduledHour / scheduledMinute) werden nach IANA-Zeitzone gruppiert und so verzögert, dass jede Zone zur lokalen Zeit der Empfänger landet (DST-korrekt, nicht offsetbasiert).

Weiterführendes