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 anything is written to 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. Nothing is written to Knock before this point.
Build. The agent creates partials, then layouts, then workflows, validating, pushing, reading back, and committing each stage to your Development environment.
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 promoting to production.

Prerequisites

Before getting started, you'll need the following:

A Knock account with a configured email provider. Navigate to Integrations > Channels in your dashboard to set this up if you haven't already.
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.
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 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 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 rather than one per layout 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 session you'll launch your agent 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 for verification
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
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: it confirms that the CLI is authenticated, finds your email channel in Knock, checks that the MCP server is connected, and inventories any workflows, layouts, and partials already in your Development environment so that nothing gets overwritten by the migration.

The agent then asks you some intake questions. For example, it may ask you where your template files are and whether anything should be skipped, where the new Knock resource files should live in your local project directory, whether templates should be built from editable blocks (the default) or kept as raw HTML, whether to migrate into your Development environment or a branch, and any naming conventions to follow. It also asks how much of the result you want to review yourself: every email is rendered and checked against the original automatically, and you choose whether to review a side-by-side comparison for one email per layout (the default) or for every email (which needs a service token and saves each rendered email in your local workspace), and whether to also have test emails sent to your inbox.

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 content the original template's logic could never display. 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 when 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, read back from Knock to confirm it matches, and committed to your Development environment 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 the option to send test emails to your inbox, the agent sends a test for each workflow (or for an agreed sample on large sets), and waits for you to confirm them in your inbox before marking the migration verified.

Read the report and promote to production

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 need to be set in the dashboard, and instructions for promoting your migrated resources to production.

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. When you're ready, you can promote the migration's commits to your Production environment with the Knock CLI. 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 or along with 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. Most agents configure MCP servers per project directory, so a server that works elsewhere isn't automatically available in a new one.
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.