Migrate email templates to Knock with an AI coding agent

Learn how to migrate your existing email templates into Knock layouts, partials, and workflows using an AI coding agent, the Knock CLI, and the Knock MCP server.

Storing your email templates in Knock comes with many advantages. In this tutorial, you'll use the knock-email-template-migration skill with an AI coding agent to migrate a directory of existing email templates into Knock. The skill parses your existing templates into reusable building blocks in Knock: shared headers and footers become email layouts, repeated components become partials that can be used as blocks in the dashboard's template editor, and each email is added as a channel step on a workflow with a documented trigger payload.

The skill does the analysis, planning, building, and verification to ensure that the migrated templates are a faithful representation of the original. You'll answer a few questions up front, approve the plan before the agent builds anything in Knock, and sign off on the final result.

How the migration runs

The skill runs in five phases and keeps a record of each decision it makes along the way. This record can be used to resume a migration from where it left off, or take a second pass over more templates later.

Preflight and intake. The agent checks that the Knock CLI and MCP server are available and connected, inventories the resources already in your Knock account, copies your templates into your local workspace, and confirms its intake answers with you.
Analyze. The agent groups your templates by shared content, then analyzes them one at a time.
Plan and checkpoint. The agent proposes its plan for layouts, partials, variable mapping, and workflows, then stops for your approval. Apart from a test recipient for rendering previews, nothing is written to Knock before this point.
Build. The agent creates partials, then layouts, then workflows, validating, pushing, and reading back each one. Partials and layouts are committed as they're built. If you've enabled environments, workflows are committed to your development environment too; if not, they stay unpublished drafts.
Verify and report. The agent renders every template, compares it to the original, and writes a final report with the trigger payload contract for each workflow and instructions for publishing your workflows, or for promoting them to production if you've enabled environments.

Prerequisites

Before getting started, you'll need the following:

A Knock account.
Your email template files. Knock supports HTML and MJML natively; component-based templates such as React Email need to be rendered to HTML first, and the skill will ask you to run your build if it can't. If your MJML uses custom components or mj-include files, include their definitions or share the compiled HTML.
An AI coding agent that supports agent skills, such as Claude Code, Cursor, or Codex, using the most capable model available to you.
The Knock CLI (v1.3.0 or later) installed and authenticated.
The Knock MCP server connected to your agent. See the get started section of the MCP server docs for setup instructions.
Optional: a configured email provider under Channels and sources in your dashboard's account settings. Setting this up before your migration will help you avoid necessary updates to your workflows after the migration is complete. The Knock email channel is used by default if you don't have another email provider configured.
Optional: a service token for your Knock account. This is only needed if the MCP server isn't available to your agent, or if you'd like to review every migrated email side by side, one at a time or all together, rather than a representative sample during the verification step of your migration. It's used to make requests to the management API directly.

Have an account owner or admin generate a dedicated token for the migration. In the dashboard, go to Settings > Service tokens and click + New token. Name it for the migration so it's easy to find and revoke later. The token is only shown once, so copy it somewhere secure.
In the terminal window that you'll launch your agent session from, paste the token as an environment variable export so your agent can use it without you ever pasting it into the chat:
Start your agent from that same terminal session. The skill checks for the variable when it needs it and confirms that the token authenticates successfully.
Once you complete your migration, revoke the token from its three-dot menu on the Service tokens page.

MCP capabilities

When you connect to the MCP server, you'll be prompted to select which capabilities to enable. The skill uses the following:

Capability	Requirement	Purpose
Read resources	Required	Inspect existing resources and environment variables
Manage resources	Required	Render template previews and create the environment variables you approve
Manage data	Required	Create the test recipient that previews render for
Documentation	Recommended	Look up Knock concepts and Liquid helpers during the migration
Debug	Recommended	Inspect message logs when verifying workflows with branch or step conditions

Install the skills

Install the migration skill along with the knock-cli skill, which teaches your agent the CLI mechanics the migration relies on:

Run this command from the project directory where you want the migration to live. Skills activate automatically when you ask your agent for a related task.

Background

While not required reading, you may want to familiarize yourself with the following Knock concepts so you can follow the agent's plan and the questions it asks:

Workflows and channel steps
Email layouts
Partials
Referencing variables and your Knock data in templates
Knock Liquid helpers
Version control, including commits and environments

Migration steps

Start the migration

Open your agent in the project directory and prompt it to begin your migration. Some agents may require you to invoke the skill explicitly with /knock-email-template-migration or $knock-email-template-migration.

The skill will activate and run the preflight phase to make sure that your agent has access to everything it needs.

Next you'll answer some intake questions. For example, it may ask you questions about your templates, where to build the migrated emails, and any naming conventions to follow. It also asks how you prefer to review the end result.

Template analysis

The agent scans your full set of templates, grouping any that share a header and footer into families, then analyzes each template and writes its findings to an analysis file in the workspace.

This phase is read-only and does not write anything to Knock. For large sets of templates, it works in batches and can spread the per-template analysis across parallel tasks if your agent supports them.

Review the migration plan

Once the analysis is complete, the agent stops for your review and approval. You'll be presented with any blocking decisions that need to be made before the migration can proceed.

Finally, you'll be asked to approve a few lists of decisions proposed by the agent, based on its analysis:

Defaults the agent will apply unless you veto them, such as inferred subject lines that are not explicitly in the source template.
Suspected source mistakes like typos or invalid conditional logic. The default is to reproduce your templates faithfully, but you can ask the agent to correct them in the migrated templates instead.
Suggested optimizations the agent will not apply unless you ask, such as moving a recipient's name to Knock's recipient namespace or a support email address to an environment variable instead of requiring these values to be passed each time you trigger the workflow.

Watch the build

With the plan approved, the agent builds in dependency order: partials first, then layouts, then one workflow per template. Each resource is validated, pushed with the CLI, and read back from Knock to confirm it matches before the next stage begins.

You don't need to do anything here beyond letting it run. If the agent hits something it can't resolve, it records the question in its MIGRATION.md file and asks for your input.

Review the verification

Once all of your resources have been created and pushed to Knock, the agent proceeds with verifying the migration result based on the review option you chose at the start. It compares your Knock-rendered emails with your original templates to ensure that everything has been migrated correctly, then offers to open the side-by-side comparison page in your browser so you can review the result. If you chose to approve every email one at a time, the agent shows you each email's comparison as soon as it's verified and waits for you to approve it or ask for changes before moving on to the next.

If you chose the option to send test emails to your inbox, the agent sends a test of each email, or of a sample you agree on for large sets, and waits for you to confirm them in your inbox before marking the migration verified. When you're approving emails one at a time, each email's test arrives as part of its approval.

Read the report and go live

The agent writes a REPORT.md file with everything it created, including a list of the reusable partial components your team can use to build new emails, open action items such as environment variables that still need to be set, and instructions for publishing or promoting your migrated workflows.

The report also includes the trigger data that each workflow expects when it's triggered; these can be shared with the engineers who will build the integrations that send these emails. The agent doesn't publish or promote your workflows, so you decide when each one goes live.

If your account has a single production environment, your migrated partials and layouts are already published and each workflow is an unpublished draft. Publish each workflow when your application is ready to trigger it, either from the dashboard or with a commit scoped to that workflow so that no one else's drafts are published with it. The report's open items also remind you to delete the test recipient the agent created.

If you've enabled environments, you can promote the migration's commits to your production environment with the Knock CLI. If the agent built on a branch, merge the branch into development first. Each resource can be promoted by commit ID so that unrelated changes pending in your development environment aren't promoted unintentionally. Partials and layouts should be promoted before the workflows that depend on them.

Troubleshooting

The preflight phase stops at the MCP check. Confirm the server is connected for this project and that the capabilities above are enabled.
A render doesn't match the original. Point the agent at the specific difference and ask it to re-verify the template.
The migration was interrupted. Start a new session in the same directory and ask the agent to continue. The skill records its progress as it works, so it can resume from where it left off.
You have more templates to add later on. Ask the agent to migrate them into the same directory. The skill reuses the layouts and partials it already built and appends a new pass to the record rather than starting over.

Frequently asked questions

Yes. Render or export them to HTML first, then run the migration on the output. The skill detects component sources and will ask you to run your build if it finds them.

There is no hard limit. The skill analyzes one template at a time, keeps track of its progress, and can spread analysis across parallel tasks, so large sets are a matter of time rather than context. For very large sets it works in batches and can resume across sessions.

If you want to migrate a small handful of templates, you can paste HTML into the Knock agent and ask it to create a layout, partial, or workflow directly. It won't perform the analysis, the plan checkpoint, or the rendered verification this tutorial describes, so for a full set of templates the skill is the better path.