Lifecycle email events: build a contract before you build a flow

‘Send welcome’ is a command with hidden policy. ‘Account signup confirmed’ is a statement about an occurrence whose meaning the product can define. The latter lets consumers decide whether a welcome is appropriate without treating every producer as an authority to dispatch mail. Name the event for a durable business fact, not a page view that happens to correlate with it.

For our hypothetical guide signup, define whether confirmation means the address was verified, the request was stored, or a broader subscription was established. Those are different facts. Include only what the producer can actually attest to. Document the owner of that meaning and the system of record. If the meaning changes, treat it as a contract change rather than continuing to emit a familiar name with incompatible semantics.

CloudEvents identifies distinct events through the combination of source and id and allows duplicate resends to keep the same identity. It also distinguishes context from event data. Apply those concepts to deduplication and routing, while separately defining your business schema. A UUID-shaped string alone does not tell a consumer whether two records describe one occurrence or two.

Keep contact or account identity separate from event identity. A person can legitimately request two different resources; collapsing every event by email address would erase useful work. Conversely, two deliveries of the same request should not create two welcomes. Define the schema version, required fields, accepted values, and handling of unknown versions. Validate before enrollment. Put sensitive data in the payload only when needed, and avoid embedding personal details in source identifiers, metrics labels, or event names.

Reference: CloudEvents specification 1.0.2

A schema describes the record; a consumer contract explains what your workflow does with it. The following outline uses a fictional resource-request event. It deliberately separates authoritative facts from send decisions. Fill in the actual policy, destinations, and retention rules before implementation.

A schema validator should reject missing required facts rather than allowing an agent to invent them. Unknown optional fields may be acceptable under your compatibility policy; unknown meaning is not. Record a failure reason that an operator can understand, without copying unnecessary personal data into the error. Keep malformed input out of the runnable queue, and provide a controlled route for correction or quarantine.

Occurrence: a confirmed request for an approved resource
Identity: source + event id; stable across delivery retries
Subject: internal contact id scoped to the correct workspace
Facts: resource id, request occurrence time, schema version
Consumer: verify resource destination and current eligibility
Deduplication: one fulfillment job for this occurrence and purpose
Expiry: discard stale help according to an explicit policy
Exit: fulfilled, ineligible, invalid, expired, or awaiting authoritative facts

A queue may deliver an old event after a newer one. Store when the occurrence happened and when your system received or processed it. Do not infer business order solely from network arrival. If a signup-confirmed event arrives after an unsubscribe, the consumer should consult current eligibility rather than assume the most recently delivered event represents the latest choice.

Decide which messages are historical obligations and which are time-sensitive help. A receipt for a completed purchase and an onboarding nudge have different usefulness policies. A replay may be appropriate for rebuilding state but inappropriate for dispatching every old candidate message. Give replay mode an explicit side-effect policy. An agent summarizing a backlog should not gain authority to turn that backlog into a mass send.

If you acknowledge an event before storing the intended job, a crash can lose the work. If you create a job and crash before recording consumption, a retry can create another. Choose an atomic or otherwise recoverable boundary appropriate to your storage and transport. A unique key for the occurrence and purpose can prevent duplicate enrollment, but the later dispatch step needs its own duplicate-safe design.

Keep event-consumed, job-created, send-requested, provider-accepted, and delivered states distinct. A consumer succeeding does not prove an email was sent. Use bounded retries for transient failures and stop retrying permanent schema or policy errors. If a send request has an ambiguous outcome, reconcile it rather than blindly issuing another. The journal’s retry and webhook guides explore these downstream boundaries; no event format by itself gives you exactly-once side effects.

• Event meaning has an owner and a documented schema.
• Occurrence identity remains stable across retries.
• Current state and policy are checked before dispatch.
• Replay behavior cannot silently send historical work.
• Durable jobs and downstream dispatch have separate duplicate controls.

Build fixtures for a normal occurrence, an exact duplicate, a distinct second request, an old schema, a malformed identity, a delayed event, and a newer restriction arriving first. Add a crash between durable steps and a replay that must not send. Assert observable outcomes: one job, no forbidden job, an explained hold, or a reconciled ambiguous state. A successful HTTP response is not enough.

Use a Moosewave template for the content, but keep the event contract outside the template. Give agents trusted facts and a narrow drafting role; do not make them interpret ambiguous records as permission. Save producer and consumer tests together with the contract revision. The result is a lifecycle flow whose quiet decisions can be explained, not just a visual diagram that appears to work when events arrive in the happiest order.

• CloudEvents specification 1.0.2. Event identity, context, data, and time. The consumer policies and lifecycle contract are our proposed engineering example.

Sources checked 11 October 2026. Product behavior and documentation can change, so the linked primary source takes precedence if it differs from this article.