Sender domain migration

Tutorials

Learn how to warm up a new sending domain and protect deliverability by routing traffic gradually with channel groups.

This page covers how to migrate to a new sending domain in Knock, warming it gradually to avoid putting your email deliverability at risk. You'll set up the new domain as a new email channel in your Knock account, create a channel group containing both your new and existing email channels, and set conditions on the channel group to route traffic between the two. You'll use the channel group to raise the new domain's share of traffic on a warming schedule, retiring the old domain once deliverability is confirmed.

Prerequisites

This tutorial assumes you already have a Knock account with a configured email provider sending your production traffic, and that your new sending domain is set up and verified with a provider. SPF, DKIM, and DMARC should already be configured and passing for the new domain.

You'll also need access to the Management API to create and configure your channel group, and the Knock CLI to update your workflows in bulk.

Domain warming schedule

Plan out your warming schedule before you start routing any traffic. Use Knock's email domain warmup calculator to generate a schedule sized to your volume. As a general rule, plan for roughly 30 days to reach full volume, starting at a low daily volume and increasing it gradually as deliverability holds up at each stage. Spread each day's volume evenly across your sending window rather than sending it all in a single burst.

You can implement your channel group routing before your domain warming schedule begins. Keep your channel group conditions set to route 100% of traffic to your existing domain's channel until you're ready to begin migrating.

Traffic routing mechanisms

When planning your migration, decide which controls you'll use to route each workflow recipient run between domains. We recommend a combination of recipient-based controls and workflow allowlisting, giving you fine-grained control over what moves and when.

Route traffic based on recipient attributes. Consider targeting your most engaged users early in the domain warming process. Segment your priority recipients into an audience. This could be a static audience you add to over time, or a dynamic audience based on user properties. Reference this audience in your channel group conditions to route emails to these recipients through the new domain.
Route traffic on a per-workflow basis. To keep all traffic for your most critical workflows like password resets routed to your established domain, include a workflow allowlist in your channel group configuration. Gate critical workflows until you've built confidence in the new domain's reputation. Referencing an environment variable as the allowlist rather than hardcoding workflow keys into the condition enables you to update which workflows are included without editing the channel group itself.

We recommend considering a combination of engagement and criticality when deciding the order in which to migrate your workflows to the new domain:

High-engagement, low-criticality workflows first. For example, an alert or digest that recipients open often but where the business doesn't break if a message is delayed or missed.
High-engagement, high-criticality workflows next. Recipients reliably engage with password resets and account notifications, but their criticality means you should wait until you've validated the new domain's reputation on lower-stakes traffic first.
High-volume, low-engagement workflows last. Digests or notifications with a large recipient base but low open rates carry the most reputation risk per message and benefit most from a domain that's already established.

Set up traffic routing

Create a new email channel

Navigate to Integrations > Channels in your dashboard and add a new email channel configured with your new domain as the sender. The new domain should be configured with your provider and passing SPF, DKIM, and DMARC checks before sending any production traffic through it.

Implement control mechanisms

Before creating your channel group, set up the controls you'll use to manage the flow of traffic between domains. This might include creating a rollout audience or saving an environment variable to hold your workflow allowlist. You'll reference these in the channel group's conditions, updating your control mechanism (e.g., add users to an audience) over time to increase traffic.

We recommend starting with values that keep production traffic from matching those conditions, ensuring nothing routes to the new domain until you're ready.

Create a channel group

Using the Management API, create a channel group that contains both your existing domain's channel and your new domain's channel.

Set the group's operator to any so it routes through the first matching channel only, and order the rules with the most specific condition first:

An if rule that routes to the new domain's channel when a workflow recipient run matches your rollout criteria.
An always rule that falls back to your existing domain's channel for everyone else.

Update your workflows

After creating your channel group, update each workflow's email step to reference the channel group instead of your original email channel. With the channel group in place, all email steps will defer to your channel group conditions for routing. No other updates are required at the workflow level.

This is an account-wide change across every workflow that sends email, so we recommend making the update programmatically with the Knock CLI. Use knock workflow pull to download your workflows locally, update each email step to reference the channel group's key, then use knock workflow push to apply the change across all of them.

Note that any traffic routing enabled on the channel group will immediately go into effect after this update. We recommend keeping all traffic routed to your existing domain's channel while you make this change, so you can validate it before any behavior shifts.

Manage routing

When you're ready to begin routing traffic to the new domain, expand your rollout using whatever mechanism you set up in the "Implement control mechanisms" step. As deliverability holds up at each stage of your warming schedule, continue expanding it to route a larger share of traffic to the new domain.

After each traffic increase, check spam complaint and bounce rates. If performance softens, hold at the current volume for a few days before continuing. If it deteriorates materially, scale back the rollout the same way, routing a larger share of traffic back to your existing domain.

Frequently asked questions

Not to route them. The channel group sits between your workflow and the underlying channels, so the same template renders and sends regardless of which domain the channel group routes to. If your templates reference the sending domain directly (for example, in a template-level from field), review those references before starting the migration.

A rebrand alongside the migration will also require a branding update anywhere you're using a brand name, logo, or color. Your branding properties live at the account level and render through the vars.branding.* namespace, so updating them in your account settings changes every message you send at once.

If you want to stage the change ahead of time, gate your new branding on an environment variable and update your layouts wherever branding renders:

When you begin routing traffic to the new sending domain, flip the variable in production so every message carries the new branding. Flipping it back reverts your branding if you need to roll back.

Once the migration is complete, update your branding properties in your account settings to your new assets and remove the conditions from your layouts. Your layouts go back to reading vars.branding.* directly, with no leftover migration logic.

Knock's custom domains feature controls the domain used for link tracking and the hosted preference center, and is configured independently of your sending channels. Changing your sending domain has no effect on either one until you reassign the custom domain yourself.

Move your tracking domain when you start routing production traffic to the new sending domain. A custom tracking domain is assigned to an environment as a single value, so it applies to every message that environment sends. There's no way to split tracking between two domains the way a channel group splits sending, which means the cutover is all or nothing.

Inbox providers weigh how closely your sending domain and the domains in your links align, so a mismatch works against the domain you're trying to warm. Your existing domain already has an established reputation and is on its way out, so favor the new domain: set up a tracking subdomain of it, verify it, and assign it to your production environment as your first traffic moves over. Messages already sent through the old tracking domain keep working as long as that domain stays verified in Knock with its DNS record intact.

Yes. Because your workflows reference the channel group rather than a specific channel, you can adjust the routing rules to stop sending traffic to your new domain at any time. All email steps will fall back to your original domain's channel.