Classic Email Template Migration

Classic Email Template Migration

This skill activates when a practitioner needs to convert Classic email templates (Text, HTML with Letterhead, Custom HTML, Visualforce email) to Lightning Email Templates and rewire all downstream consumers.

Before Starting

Gather this context before working on anything in this domain:

• Inventory templates by type. SELECT Id, Name, TemplateType, FolderId, IsActive FROM EmailTemplate WHERE UiType = 'Aloha' returns Classic templates. TemplateType is one of text, html (with Letterhead), custom (raw HTML), visualforce.
• Identify the downstream consumers per template: Email Alerts (SELECT Id, FullName FROM WorkflowAlert WHERE TemplateId = :t), Flow Send Email actions, Process Builder email actions, Apex code calling Messaging.SingleEmailMessage.setTemplateId(t), and any Marketing/CRM campaign that references the template.
• Confirm the org's brand strategy: do you have an Enhanced Letterhead already, or will the migration create one from the existing Classic Letterhead images? Letterhead colors, logos, and footers must survive the migration intact.
• Determine OrgWideEmailAddress usage. Templates often pair with a specific sender ("noreply@", "sales@"). Lightning Email Templates do not store sender — that's set at send time — so the migration must preserve the pairing in downstream Email Alerts and Apex.

Core Concepts

1. Template Type Mapping

Visualforce email templates are the only type that cannot be converted automatically. Their power (full Apex controllers, conditional logic, related-list iteration) has no Lightning equivalent. The migration decision is per-template: keep it as Classic (still supported), or rewrite the required logic in Lightning + an Apex helper that builds the body string and uses setHtmlBody() instead of setTemplateId().

2. Merge Field Syntax Translation

3. Letterhead vs Enhanced Letterhead

Classic Letterhead and Enhanced Letterhead are two different Letterhead and EnhancedLetterhead sObjects with no auto-conversion path. Migration requires:

You build the Enhanced Letterhead once per brand; many Lightning Email Templates can reference the same Enhanced Letterhead.

4. Downstream Consumer Rewiring

Every reference to a Classic template ID must be updated. Lightning template IDs are different IDs, so blanket text substitution is not enough — you need a mapping table.

5. UiType: The Single Distinguishing Field

EmailTemplate.UiType distinguishes Classic from Lightning:

Filter queries by UiType to operate on the right cohort. A WHERE UiType = 'Aloha' query is your migration source set; WHERE UiType = 'SFX' is the destination set.

Common Patterns

Pattern 1: Direct Conversion of Custom HTML Template

When to use: Classic Custom HTML templates without Visualforce or merge formulas.

How it works:

1. Open the Classic template; copy the raw HTML body.
2. In Setup → Email Template Builder, create a new Lightning Email Template; choose the "HTML" type with no letterhead (or with the new Enhanced Letterhead if applicable).
3. Switch the builder to source-code view; paste the HTML.
4. Replace merge fields per the syntax table (Section 2).
5. Send a test email to a sandbox user; verify rendering across major clients (Outlook, Gmail, mobile).
6. Save and capture the new template ID for downstream rewiring.

Why not the alternative: The Lightning Email Template Builder's WYSIWYG editor cannot import a Classic template directly — it can only build from blocks or accept HTML source. Trying to recreate the layout in the visual editor is slower and lossy compared to pasting the original HTML.

Pattern 2: HTML-with-Letterhead Template + Enhanced Letterhead Build-Out

When to use: Classic templates that share a single Letterhead (typical: one corporate Letterhead + 30 templates that reference it).

How it works:

1. Build ONE Enhanced Letterhead first. In Setup → Enhanced Letterheads, recreate the brand (header image, colors, footer).
2. Verify rendering by attaching the Enhanced Letterhead to a single test Lightning Email Template.
3. For each Classic template that referenced the Classic Letterhead, create a new Lightning Email Template that uses the Enhanced Letterhead.
4. Copy the body HTML from the Classic template into the Lightning template body block.
5. Translate merge fields.
6. Map each old → new template ID for downstream rewiring.

Why not the alternative: Building Enhanced Letterheads per template scatters brand maintenance and makes future brand updates painful. One Enhanced Letterhead serving N templates is the right architecture.

Pattern 3: Visualforce Email Template — Decide Per Template

When to use: Classic templates with TemplateType='visualforce' that contain Apex controller logic (related-list iteration, conditional content, complex formatting).

How it works:

1. For each VF template, audit what the controller does. Categorize: (a) simple merge fields (no real Apex needed), (b) related-list rendering, (c) genuine business logic.
2. Category (a): Re-create as Lightning Email Template with merge fields. Discard the VF template.
3. Category (b): Decide if Lightning Email Template's {{#each}} over a related list is sufficient (it can iterate, but not all relationships); if not, keep VF or move logic to an Apex helper that builds the body string.
4. Category (c): Keep as Classic Visualforce email template. Document the retention reason. Salesforce continues to support these.

Why not the alternative: Forcing a category (c) template into Lightning by hand-coding the logic in Apex setHtmlBody() is technically possible but loses the template-builder maintenance UX (admins can't tweak the email; only developers can). Keep VF when the logic justifies it.

Pattern 4: Bulk Email Alert Repointing

When to use: After templates are migrated, dozens or hundreds of Email Alerts still point at Classic template IDs.

How it works:

1. Build the old → new template ID mapping table (CSV or Map<Id, Id> in Apex).
2. Retrieve all Email Alerts via Metadata API as XML.
3. For each <workflowAlert> referencing an old template ID, update the <template> element to the new template's full name.
4. Deploy the updated metadata in a single change set or DevOps Center release.
5. Verify via SOQL: SELECT Id, FullName, TemplateId FROM WorkflowAlert WHERE TemplateId IN :oldIds should return zero after deploy.

Why not the alternative: Editing each Email Alert in the Setup UI is feasible at <10 alerts; at scale it is error-prone and slow. Metadata API is the right tool above ~10 alerts.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Inventory and categorize. Run the WHERE UiType='Aloha' SOQL. Group by TemplateType. Generate a CSV with columns: ID, Name, Type, Folder, downstream consumers (count of Email Alerts, Flows, Apex references). This drives the migration plan.
2. Build Enhanced Letterhead(s). For each unique brand layout in Classic Letterheads, create an Enhanced Letterhead. Keep the count low (1–3 per org); resist per-department variants that fragment brand.
3. Migrate templates by type. Start with Text and Custom HTML (lowest risk, highest volume) — paste body, translate merge fields, send test, capture new ID. Then HTML-with-Letterhead per Pattern 2: each new Lightning template references the Enhanced Letterhead; body content ports directly.
4. Triage Visualforce templates. Categorize each per Pattern 3. Most simple ones become Lightning; complex ones stay as VF with a documented retention rationale.
5. Build the old → new ID mapping table. Persist as a custom object (Email_Template_Migration_Map__c) for ongoing reference and audit.
6. Rewire downstream consumers. Email Alerts via Metadata API (Pattern 4), Flows via Flow XML edit, Apex via code change. Verify zero references to old template IDs remain.
7. Verify and deactivate Classic templates. Send test emails through every Email Alert and Flow path. Once confirmed, set Classic template IsActive=false (don't delete — keep as audit trail). Schedule deletion after a soak window if storage is a concern.

Review Checklist

Run through these before marking work in this area complete:

• Every Classic template has either a Lightning equivalent OR a documented "keep as VF" retention reason
• Enhanced Letterhead(s) match the original brand (header image, colors, footer); rendered tested in Outlook, Gmail, Apple Mail
• Merge fields translated to {{Recipient.X}} / {{Sender.X}} / {{Related.X}} syntax
• No {!IF(...)}, {!CASE(...)}, or {!System.X} merge formulas remain (Lightning doesn't support them)
• Old → new template ID mapping table is committed and accessible to ongoing operations
• All Email Alerts updated via Metadata API; verification SOQL returns zero references to old template IDs
• All Flow Send Email actions updated to new template IDs
• All Apex setTemplateId() calls updated and deployed
• OrgWideEmailAddress sender pairings preserved on each downstream consumer
• Test email path validated end-to-end for at least one alert per template
• Classic templates set to IsActive=false after verification (not deleted yet)

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Lightning Email Templates have no IF/CASE merge formula support. Classic templates often used {!IF(Contact.Email != null, Contact.Email, 'fallback')} for inline conditional content. Lightning templates have no equivalent — the merge engine is straight field interpolation. Migrate the conditional logic upstream: create a formula field on the record (Best_Contact_Email__c = IF(Email != null, Email, 'fallback')) and merge that field instead.

2. Custom Setting and $Setup merge fields don't translate. Classic templates could reference {!$Setup.MyCustomSetting__c.URL__c}. Lightning has no equivalent merge namespace for custom settings. The fix is to surface the value via a record field (formula or text) on whatever record is being merged.

3. Visualforce email templates remain functional but invisible in some Lightning UIs. When you select a template in the Lightning Send Email composer, only Lightning templates appear in the picker by default. Visualforce templates show only when explicitly enabled in the user's Email Settings or via the "Show Classic Templates" toggle. Users may report "the template is missing" when it actually exists but is hidden.

4. UiType is a separate field from TemplateType. Classic and Lightning templates can both have TemplateType='html'. The distinguishing field is UiType — Classic is 'Aloha', Lightning is 'SFX'. Migration scripts that filter only by TemplateType will mix Classic and Lightning templates and produce wrong results.

5. Folder permissions don't auto-port. Classic templates lived in Email Template Folders with their own sharing model. Lightning templates also use folders, but a Lightning Email Template Folder is a separate Folder object record. Replicating the folder structure and folder-level sharing is a manual step in the migration; otherwise users may not see migrated templates they had access to in Classic.

6. Letterhead images served from old URLs may be cached or moved. Classic Letterhead headers/footers were often hosted as Documents or external URLs. After migration to Enhanced Letterhead, if the image URL changed (e.g., new Document ID), some recipients' email clients may have cached the old URL with broken-link indicators. Test rendering on real email clients, not just the Salesforce preview.

7. Email Alert setTemplateId requires the template to be in a folder the running user has access to. Even when an Email Alert references the new Lightning template by ID, send-time access is checked against the user firing the alert. Lightning Email Template folders need explicit sharing to the running profiles or permission sets, or alerts will fail with INVALID_FIELD: TemplateId is invalid.

8. OrgWideEmailAddress is set on the Email Alert / Apex call, not the template. Classic templates were sometimes paired with a specific from-address via the template setup screen. Lightning templates have no sender field. Re-setting the OrgWideEmailAddress on the downstream Email Alert (or in Messaging.SingleEmailMessage.setOrgWideEmailAddressId() in Apex) is part of the migration — it's not preserved automatically because it was never on the template object.

Output Artifacts

Related Skills

• admin/email-templates-and-alerts — Use when designing new Lightning templates and Email Alerts (post-migration)
• apex/apex-outbound-email-patterns — Use when Apex code sends transactional email; affected by template ID changes
• flow/flow-email-and-notifications — Use when Flow's Send Email actions need to be updated to new template IDs
• admin/email-deliverability-strategy — Use to verify post-migration deliverability and bounce-rate baselines remain stable
• lwc/visualforce-to-lwc-migration — Use when retained Visualforce email templates also have associated VF UI pages being migrated