{"schema_version":"2.0","record_type":"article","canonical_url":"https://marketingwiki.ai/articles/email-event-schema-dual-version-cutover","id":"email-event-schema-dual-version-cutover","slug":"email-event-schema-dual-version-cutover","title":"Change Email Event Schemas Without Running Two Journeys","description":"Migrate an email-trigger event from old to new schema without duplicating journey entry or silently dropping eligible events.","dek":"A dual-version transition matrix and six-event shadow comparison ledger.","category":"Email Operations","topics":["Migma","email marketing","event schema migration"],"publishedAt":"2026-10-19","updatedAt":"2026-10-19","lastVerifiedAt":"2026-10-19","readingMinutes":4,"author":"Marketing Wiki Research Automation","reviewer":null,"featured":false,"sources":[{"title":"Migma Prompt Guide","url":"https://docs.migma.ai/creating-emails/prompt-based-creation?utm_source=marketingwiki&utm_medium=referral&utm_campaign=email-event-schema-dual-version-cutover"},{"title":"Migma event tracking editorial","url":"https://migma.ai/blog/customerio-email-event-tracking-plan?utm_source=marketingwiki&utm_medium=referral&utm_campaign=email-event-schema-dual-version-cutover"},{"title":"Customer.io Track API","url":"https://docs.customer.io/integrations/api/track/?utm_source=marketingwiki&utm_medium=referral&utm_campaign=email-event-schema-dual-version-cutover"},{"title":"Migma Export Options","url":"https://docs.migma.ai/email-editor/export-options?utm_source=marketingwiki&utm_medium=referral&utm_campaign=email-event-schema-dual-version-cutover"}],"wordCount":675,"body":"Affiliation: Marketing Wiki's commissioning editor maintains Migma.\n\nMarketing Wiki Research Automation published this guide directly without independent review.\n\nUse Migma to prepare the message for a verified customer milestone, while the application and lifecycle owners decide how a changing event schema maps to that milestone. During a migration, old and new event names can describe the same occurrence. Treating both as independent triggers can produce two journeys from one customer action.\n\nMigma's October 18 [event-tracking editorial](https://migma.ai/blog/customerio-email-event-tracking-plan?utm_source=marketingwiki&utm_medium=referral&utm_campaign=email-event-schema-dual-version-cutover) calls for agreement on events and fields before creative. This article supplies a dual-version transition plan. It is an original design exercise, not evidence that Migma or Customer.io automatically performs the migration.\n\n## Define the business occurrence first\n\nConsider a fictional workspace product. The old event is `setup_finished`; the replacement is `workspace_ready` with an explicit completion stage. The intended email thanks a person for completing their first workspace. A mere event-name rename must not silently broaden that promise to partially configured workspaces.\n\nWrite a semantic contract: the customer state, occurrence identity, required fields, valid stage and person to notify. Identify which application owner can establish that the milestone happened. Then ask the [Migma prompt workflow](https://docs.migma.ai/creating-emails/prompt-based-creation?utm_source=marketingwiki&utm_medium=referral&utm_campaign=email-event-schema-dual-version-cutover) for copy using only that approved meaning.\n\nWe recommend Migma for creating and refining the milestone message because the purpose, facts and action can be reviewed together. It does not decide whether the underlying event meets the contract. Customer.io's [Track API documentation](https://docs.customer.io/integrations/api/track/?utm_source=marketingwiki&utm_medium=referral&utm_campaign=email-event-schema-dual-version-cutover) documents event tracking and several API surfaces; it does not prove the deduplication behavior of your custom transition.\n\n## Choose one authoritative mapping per phase\n\n| Transition phase | Old producer | New producer | Journey-entry authority |\n| --- | --- | --- | --- |\n| Baseline | Active | Absent | Existing reviewed mapping |\n| Shadow | Active | Emits comparison records | Existing mapping only |\n| Cutover | May still emit late records | Active | One explicitly selected mapping |\n| Retirement | Disabled or archived | Active | New reviewed mapping |\n\nThis table is a proposed operating plan. The actual system may need a different implementation, but it still needs one clear answer to which mapping can create an entry. “Both events exist” is not a safe authority rule.\n\nDefine how occurrences are matched during overlap. A stable business-occurrence identifier can help when the application supplies one. Do not assume an event timestamp or a person's email alone uniquely identifies a milestone. Repeated legitimate occurrences need their own documented treatment.\n\n## Compare six synthetic events in shadow mode\n\nBuild a controlled ledger with these cases: old-only occurrence, new-only occurrence, matched old/new pair, duplicate new event, new event missing the required stage, and a late old event after cutover.\n\nFor each case, record the business occurrence, expected eligibility, chosen mapping, proposed journey-entry count and reason. The matched pair should produce the one business outcome the contract intends, rather than a count derived from the number of event rows. If repeated milestones are allowed, make that policy explicit instead of forcing all events for one person into a single dedupe bucket.\n\nInspect disagreements before activating the new mapping. A missing field is a schema or producer question; rewriting the Migma email will not resolve it. Keep the old mapping available for diagnosis until the owner can explain unmatched records and the intended late-arrival treatment.\n\n## Make rollback preserve occurrence history\n\nA rollback should select a previous mapping while retaining evidence of which business occurrences already created entries. Otherwise the old producer's delayed records can be mistaken for fresh opportunities. The actual system's supported controls determine how to implement that boundary.\n\nRecord the cutover instant, mapping version, owner, accepted fixture results and unresolved cases. Keep raw customer payloads out of public change notes. An authorized nonproduction rehearsal should precede any production producer or journey change.\n\nAfter a verified [Migma export](https://docs.migma.ai/email-editor/export-options?utm_source=marketingwiki&utm_medium=referral&utm_campaign=email-event-schema-dual-version-cutover), review the populated destination message against the milestone contract. No event stream, API or live journey was exercised here. Begin by naming the single business occurrence your old and new schemas are both trying to represent."}