Campaign Internals

This page is the developer reference for the campaign send path on the Convex backend — what happens between a user clicking Send and a recipient's mailbox. It covers the two lifecycle state machines, the send pre-flight gate, the orchestrator pipeline, the per-recipient emailSends records, and the rate-limited workpools. For the user-facing walkthrough see Send & Monitor a Campaign; for how the audience is resolved into recipients see Audience Internals.

Campaign lifecycle state machine

The campaign's status field is written by exactly one module — apps/api/convex/campaigns/lifecycle.ts. Its public transition mutation is the only writer of campaigns.status and the companion fields it patches alongside it (sentAt, cancelledAt, scheduledAt, contentBlockReason, and the stats-zero block on send). Direct ctx.db.patch of status anywhere else is a layering violation.

The six statuses

Legal edges

The reducer rejects any transition not in LEGAL_EDGES. There is no exception thrown — an illegal call returns { ok: false, reason: 'illegal_edge' }, and a transition out of a terminal status returns reason: 'terminal'. Callers translate the outcome into a user response.

A self-loop (from === to) is idempotent: it writes an audit-log row, returns applied: 'recorded', and emits no patch, no scheduler hop, and no PostHog event. This is what makes a re-fired scheduler tick safe.

Effects

The reducer is pure: given the loaded campaign, the typed input, and a userId, it returns a patch plus a list of effects. A separate runner applies them in order, atomically with the row patch. Four effect kinds exist:

The userId argument discriminates user-driven from system-source transitions. User-facing mutations pass session.userId; internal callers pass a 'system:<source>' tag (e.g. 'system:scheduler_tick', 'system:content_scan', 'system:orchestrator', 'system:send_completion'). The audit log records the tag verbatim, and the track_event effect is suppressed for any system:-prefixed caller — so background transitions never pollute PostHog.

Reaching sent: batch completion

→ sent is not driven by the user. Each per-send workpool callback advances its own emailSends row, but the campaign itself only completes when its last queued send leaves the queue. tryCompleteCampaign (in the same module) is the shared guard, called from two places:

• reconcileCampaignCompletion — the per-send entry point, invoked from the workpool completion callback after every send reaches a terminal status. A cheap no-op until the campaign is genuinely done.
• reconcileSendingCampaigns — a safety-net cron (process scheduled campaigns runs every minute; this sweep also runs every minute as reconcile sending campaigns) that reconciles every campaign still in sending. It catches callbacks that errored or final sends transitioned by a provider webhook rather than the workpool.

tryCompleteCampaign only advances to sent when all of these hold: status is sending; the checkpointed send walker has finished streaming (no campaignSendJobs row still in phase resolving); an A/B test (if any) has reached winner_selected (otherwise the second-wave remainder send would be skipped); at least one emailSends row exists; and no emailSends row remains in queued. queued is the sole non-terminal send status, so its absence means the campaign is done.

A/B test lifecycle and the remainder-send guarantee

The abTestStatus column has its own machine in apps/api/convex/campaigns/abTestLifecycle.ts — same row, different column, separate graph. Its transition mutation is the only writer of abTestStatus and its companions (abTestConfig, abWinner, abWinnerSelectedAt, and the variant-stat reset block on disable).

Two effects guarantee the held-back audience is never orphaned:

• schedule_auto_winner fires on → testing when winnerCriteria is not manual and testDuration (hours) is set. It schedules campaigns.abTest.autoDeclareWinner after the test window. Without it, an open_rate / click_rate campaign (the wizard default) would sit in testing forever and the 40–60% remainder audience would never be sent. Manual criteria instead rely on the user clicking a "choose winner" button, which the report page surfaces only for manual.
• schedule_winner_remainder fires on → winner_selected. It schedules campaigns.send.sendCampaignWinnerToRemainder (the second-phase orchestrator, below) to deliver the winning variant's content to everyone who was held back.

Send pre-flight validation

Before any caller transitions a campaign to scheduled or sending, it runs the pre-flight in apps/api/convex/campaigns/preflight.ts. The lifecycle reducer trusts its input — it does not re-validate readiness — so pre-flight is the single gate that the four send/schedule entry points (and the orchestrator at fire time) share.

validateReadyToSend returns a PreflightResult union; the first failing check wins. The ordered checks are:

The validateReadyToSendQuery internal query wraps the same logic so the orchestrator can re-run pre-flight at fire time — catching state that drifted between the original schedule call and the scheduler tick (org went suspended, template deleted, domain verification expired).

The send orchestrator

campaigns.send.startCampaignSend (apps/api/convex/campaigns/send.ts) is the single live action that takes a campaign from scheduled | sending through the full prep pipeline. It is fired by three producers: the processScheduledCampaigns cron tick, the lifecycle's schedule_campaign_send_orchestrator effect, and a direct reschedule in campaigns/scheduling.ts. It is the only writer of emailSends.abVariant and the only first-phase caller of enqueueCampaignEmails.

A/B fanout details

resolveAbFanout (campaigns/sendVariantSplit.ts) returns a fanout only when the campaign isABTest, abTestStatus === 'testing', and a config is present — so a winner_selected or pending campaign never first-phase-splits. The split is a deterministic FNV-1a hash of (campaignId:contactId) (hashFraction) compared against testFraction = 2 × splitPercentage / 100: h < testFraction is the test cohort (sub-bucketed A/B at the cohort midpoint via variantForHash), and h >= testFraction is the held-back remainder. Recipients stream page-by-page through the checkpointed send walker (resolveCampaignPage) — they are never shuffled or materialized in full.

The held-back remainder is not sent in the first phase. After a winner is declared, the second-phase action campaigns.send.sendCampaignWinnerToRemainder resolves the audience again, excludes every contact that already has an emailSends row for this campaign (covering the test cohort and guarding against double-sends), and enqueues the winning variant's content to the rest. Both phases share the per-variant enqueueVariantBatch helper — the single site that creates emailSends rows and schedules enqueueCampaignEmails.

emailSends records and "ever-reached" stat semantics

Each recipient of a campaign gets one emailSends row (apps/api/convex/schema/campaigns.ts). The contact's email, first name, and last name are snapshotted at send time and never updated — the row is the audit trail of what was actually sent, not a live view of the contact. status is a single field with eight values; queued is the only non-terminal one.

Status writes go through one writer — internal.delivery.sendLifecycle.transition with a SendRef { kind: 'campaign', id }. The legacy per-event mutations in delivery/sends.ts (the emailSends-table mutation module) were removed; that module now only reads, creates (single via create and batched via createBatch), and deletes.

getStatsByCampaign and the other per-send aggregate reads bound their scans (typically take(10_000)); campaigns larger than that should rely on the denormalized stats* counters on the campaign row, which the send lifecycle bumps per recipient.

Campaign vs transactional workpools and rate limiting

Email sends run through two separate Convex workpools defined in apps/api/convex/delivery/workpool.ts:

Two pools keep transactional mail from being blocked behind a long campaign queue. The combined ~50/sec stays under provider rate ceilings with a safety margin. Both pools set retryActionsByDefault but maxAttempts: 1 — exactly one worker run and no pool-level retry. The send-side retry loop is owned solely by the dispatch helper (lib/sendProviders/dispatch.ts, ADR-0020); a pool retry would re-run the whole worker and risk duplicate sends. The 1s/base-2 backoff fields exist but are never exercised at maxAttempts: 1.

The orchestrator's enqueueVariantBatch schedules enqueueCampaignEmails, which calls campaignEmailPool.enqueueAction once per recipient, targeting internal.delivery.worker.sendSingleEmail. Each enqueue wires the completion callback to internal.delivery.sendCompletion.completeSend and carries a typed sendRef in the workpool context so the completion module can translate worker outcomes into send-lifecycle transitions uniformly. Standard sends are scheduled immediately in chunks of 50; timezone-aware sends (useRecipientTimezone plus scheduledHour / scheduledMinute) are grouped by IANA timezone and delayed so each zone lands at the recipient's local time (DST-correct, not offset-based).

Related reading