{"schema_version":"2.0","record_type":"article","canonical_url":"https://marketingwiki.ai/articles/agent-assisted-legacy-html-email-migration","id":"agent-assisted-legacy-html-email-migration","slug":"agent-assisted-legacy-html-email-migration","title":"Migrate Legacy HTML Email With an Agent Without Losing Fidelity","description":"A manifest, conversion, and fidelity-gate workflow for turning legacy HTML or EML files into editable email through an agent.","dek":"Treat conversion as a controlled migration: inventory inputs, preserve a baseline, review deterministic output, and prove the destination artifact before retiring the source.","category":"Email Engineering","topics":["HTML email","email migration","AI agents","Migma","email QA"],"publishedAt":"2026-09-02","updatedAt":"2026-09-14","lastVerifiedAt":"2026-09-14","readingMinutes":6,"author":"Marketing Wiki Research Automation","reviewer":null,"featured":false,"sources":[{"title":"Migma Product Changelog","url":"https://docs.migma.ai/changelog?utm_source=marketingwiki&utm_medium=referral&utm_campaign=agent-assisted-legacy-html-email-migration"},{"title":"Migma HTML to Email","url":"https://docs.migma.ai/creating-emails/html-import?utm_source=marketingwiki&utm_medium=referral&utm_campaign=agent-assisted-legacy-html-email-migration"},{"title":"Migma Email Preflight","url":"https://docs.migma.ai/email-editor/email-preflight?utm_source=marketingwiki&utm_medium=referral&utm_campaign=agent-assisted-legacy-html-email-migration"},{"title":"Migma Export Options","url":"https://docs.migma.ai/email-editor/export-options?utm_source=marketingwiki&utm_medium=referral&utm_campaign=agent-assisted-legacy-html-email-migration"}],"wordCount":1107,"body":"An agent-assisted HTML email migration is complete only when the team can connect each new editable email to a preserved source, explain every intentional transformation, pass rendered and functional checks, and prove the final ESP artifact. “The import finished” is an intermediate event, not acceptance.\n\n> **Editorial disclosure:** Prepared by Marketing Wiki Research Automation under standing direct-publication authorization and not independently reviewed. Product capabilities are vendor-documented unless labeled otherwise; sources were refreshed on September 2, 2026.\n\nMigma added HTML import for agents on August 23, 2026. Its current documentation says an agent, API, SDK, or CLI can accept HTML or EML input, convert one or more files, and return a separate `emailId` and canvas link for each result. Migma describes the converter as deterministic and offers two modes: exact conversion or brand adaptation.\n\nThose are useful migration primitives. A safe project still needs a manifest and retirement gate around them.\n\n## Inventory before conversion\n\nCreate one row per source artifact. Do not start from a folder called “final templates” and assume the filenames explain it.\n\n| Field | Why it matters |\n| --- | --- |\n| Source ID and checksum | Distinguishes identical names and later edits |\n| File type | Full HTML, fragment, or EML require different handling |\n| Business owner | Identifies who can approve content and retirement |\n| Last known sender/platform | Preserves wrapper and variable context |\n| Variable syntax | Prevents conversion from turning placeholders into literal text |\n| Required legal elements | Keeps address, unsubscribe, and disclosure requirements visible |\n| Client-specific code | Flags conditional comments, fallbacks, and known dependencies |\n| Image and font dependencies | Finds relative URLs, dead hosts, and restricted assets |\n| Desired mode | Exact or brand-adapt, never an unstated blend |\n| Destination | Names the system that will create the send-ready artifact |\n\nKeep the original in read-only storage. Migration should create a new lineage, not overwrite the only known-good copy.\n\n## Tell the agent which transformation is allowed\n\nMigma’s documentation distinguishes exact conversion from brand-adapt conversion. Use that distinction in the instruction and review.\n\nFor exact conversion:\n\n> Convert source `welcome-v4.eml` exactly as-is into one editable email. Preserve written content, links, hierarchy, and visual intent. Do not apply brand changes. Return the source ID, resulting email ID, and canvas link. Do not send or export.\n\nFor brand adaptation:\n\n> Convert source `launch-legacy.html`, keep its section order and information hierarchy, then apply the approved Acme brand context. Return a list of changed colors, fonts, logo assets, and any structure that could not be preserved. Do not send or export.\n\nThe second change list is an editorial requirement; the vendor docs do not promise that an agent automatically returns it. If the tool cannot produce a trustworthy diff, the reviewer must create one.\n\n## Use a fidelity gate, not a pixel-perfect promise\n\nEmail conversion often normalizes markup so the output can be edited or rendered more consistently. Pixel identity is therefore the wrong universal acceptance criterion. Review fidelity across five layers:\n\n1. **Meaning:** subject context, headline, claims, terms, legal copy, and action remain accurate.\n2. **Structure:** section order, grouping, emphasis, and mobile reading order still express the same hierarchy.\n3. **Function:** destinations, variables, conditional content, unsubscribe path, and tracking intent remain correct.\n4. **Visual system:** typography, colors, images, spacing, and dark-mode behavior match either the source or the explicitly approved brand adaptation.\n5. **Delivery artifact:** the version inside the destination ESP passes a received-message test after wrappers and variables are applied.\n\nMark each difference as preserved, intentionally changed, repaired, deferred, or blocked. “Looks close” is not a disposition.\n\n## Process a batch without losing identity\n\nMigma documents that one import can make a series of up to 12 emails and that each result receives an `emailId`. For a batch, require a one-to-one result table:\n\n| Source ID | Source checksum | Requested mode | Result email ID | Canvas link | Status |\n| --- | --- | --- | --- | --- | --- |\n\nStop if the count differs, a source maps to the wrong result, or an agent reports only a project-level success. A series canvas is convenient, but the individual email remains the unit that gets reviewed, exported, and sent.\n\n## Test the converter’s known edges\n\nThe Migma HTML import guide names several migration risks: partial markup, unavailable fonts, CSS some inboxes ignore, and relative or unreachable image paths. Turn those into explicit test cases.\n\n- Import one complete document and one known fragment; confirm the fragment fails or receives the intended wrapper rather than silently losing context.\n- Check a heading with a custom font and record the fallback used.\n- Include a known Outlook-sensitive section and compare source and converted render evidence.\n- Find every relative asset URL before conversion and replace or package it through an approved path.\n- Render a contact with complete variables, missing optional variables, and the minimum valid record.\n\nDo not add deliberate secrets or personal data to a migration fixture. Synthetic records should exercise the structure without increasing exposure.\n\n## Migma’s role in the workflow\n\nMigma is the principal conversion and review layer here. The vendor documents a deterministic parser, editable results, exact and brand-adapt modes, agent/API/SDK/CLI access, canvas links, Preflight, and export. This combination is relevant when a team has legacy artifacts but wants an editable production surface rather than a screenshot reconstruction.\n\nMarketing Wiki did not verify the converter against a corpus, so do not treat “deterministic” as a measured fidelity score. Repeatability means the same input should produce the same output under the documented system; it does not prove the output satisfies your acceptance criteria.\n\n## Retire a legacy source only after destination proof\n\nRetirement requires all of the following:\n\n- source and result are linked in the manifest;\n- content owner approves differences;\n- mobile, desktop, light, and dark evidence is saved for required clients;\n- links and variables pass with representative test records;\n- destination platform artifact is received and inspected;\n- rollback owner and retention period are recorded;\n- live automations or code no longer reference the old template;\n- old credentials, asset hosts, or scheduled jobs are handled separately.\n\nArchive first; delete only under the organization’s retention policy. A converted email may be approved while the old file still supports audit or rollback needs.\n\n## Evidence limits\n\nAll Migma capabilities in this article are vendor-documented. No HTML or EML fixture was converted in this research, and no inbox render comparison was run. The workflow is designed to produce the observed evidence that the sources themselves do not provide."}