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

| Classic Template Type | Lightning Successor | Migration Notes |
|---|---|---|
| Text | Lightning Email Template (text-only mode) | Direct content port; merge fields translate |
| HTML with Letterhead | Lightning Email Template + Enhanced Letterhead | Letterhead must be re-built as Enhanced Letterhead first |
| Custom HTML | Lightning Email Template (HTML mode, no letterhead) | Paste raw HTML into the Email Template Builder; review for inline-style compatibility |
| Visualforce email | NOT migratable — keep as Classic OR rewrite as Lightning Email Template | VF templates support full Apex logic; Lightning has no equivalent server-render |

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

| Classic Syntax | Lightning Syntax | Notes |
|---|---|---|
| `{!Account.Name}` | `{{Recipient.Account.Name}}` (when Recipient is the merge object) OR `{{Sender.Account.Name}}` | Lightning explicitly scopes to Recipient / Sender / Related Object |
| `{!Contact.FirstName}` | `{{Recipient.FirstName}}` (if recipient IS the Contact) | Lightning prefers recipient-relative paths |
| `{!Account.Owner.FirstName}` | `{{Recipient.Account.Owner.FirstName}}` | Cross-object spans work the same; just prefix with Recipient/Sender |
| `{!System.URLENCODE($Setup.MyCustomSetting__c.URL__c)}` | NOT supported | Custom setting and System merge fields don't translate; move to a related-record field if needed |
| `{!IF(Contact.Email != null, Contact.Email, 'no-email@example.com')}` | NOT supported in template body | Lightning templates don't support IF/CASE merge formulas; pre-compute on a record formula field |
| `{!Account.LastModifiedDate}` formatted | `{{Recipient.Account.LastModifiedDate}}` | Date formatting in Lightning is via the recipient's locale; no inline format spec |

### 3. Letterhead vs Enhanced Letterhead

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

| Step | Classic Letterhead | Enhanced Letterhead Outcome |
|---|---|---|
| Header image | Static image referenced by URL | Re-uploaded as Document or referenced via static URL |
| Header background color | Hex / named color | Set in Enhanced Letterhead builder |
| Body color and fonts | Inline-style settings | Lightning Email Template Builder defaults |
| Footer image and text | Static image + text block | Re-built as Enhanced Letterhead footer block |
| Sharing | Folder-based | Folder-based (`EnhancedLetterhead.FolderId`) |

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.

| Consumer | Where the template ID lives | How to update |
|---|---|---|
| Email Alert | `WorkflowAlert.TemplateId` | Edit each alert in Setup; programmatic update via Metadata API |
| Flow `Send Email` action | Flow XML (`emailTemplateId`) | Edit each Flow; deploy via Metadata API |
| Process Builder email action | Process XML | Edit; ideally migrate to Flow first |
| Apex `Messaging.SingleEmailMessage.setTemplateId()` | Code | Find/replace by old → new ID, deploy with the rest of the code |
| Approval Process email actions | Approval XML | Edit and deploy |
| Marketing tools (Account Engagement, Marketing Cloud) | External system | Update the integration mapping |

### 5. UiType: The Single Distinguishing Field

`EmailTemplate.UiType` distinguishes Classic from Lightning:

| UiType | Meaning |
|---|---|
| `Aloha` | Classic email template |
| `SFX` | Lightning Email Template (Email Template Builder) |
| `SFX_Sample` | Lightning sample template (read-only system templates) |

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

| Situation | Recommended Approach | Reason |
|---|---|---|
| Classic Text template | Direct re-creation as Lightning text template | Lowest-effort migration; merge fields translate cleanly |
| Classic HTML w/ Letterhead, single brand | Build one Enhanced Letterhead + re-create templates | Brand maintenance stays centralized |
| Classic Custom HTML | Paste HTML into Lightning Email Template source view | Faster than rebuilding in WYSIWYG |
| Visualforce template, simple merge fields only | Re-create as Lightning template; discard VF | Simpler maintenance; admin-editable |
| Visualforce template, related-list iteration | Try Lightning template iteration first; keep VF if Lightning can't model the relationship | Lightning iteration is limited to direct related lists |
| Visualforce template, complex Apex logic | Keep as Classic VF template | Lightning has no controller equivalent |
| 100+ Classic templates, all use one Letterhead | Bulk Enhanced Letterhead + scripted template creation | Manual UI re-creation doesn't scale |
| Email Alerts reference Classic templates | Metadata API bulk update with mapping table | Editing in Setup is per-alert and slow |
| Apex code uses `setTemplateId(<Classic ID>)` | Find/replace with new IDs; deploy as code change | Code change is the canonical update mechanism |
| OrgWideEmailAddress sender pairing must persist | Re-set the sender on the Email Alert / Apex call | Lightning templates don't store sender |

---

## 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

| Artifact | Description |
|---|---|
| Lightning Email Template records | `EmailTemplate` rows with `UiType='SFX'` replacing each Classic template |
| Enhanced Letterhead record(s) | One per brand; referenced by all branded Lightning templates |
| `Email_Template_Migration_Map__c` records | Old Classic ID → new Lightning ID, plus migration date and outcome |
| Updated Email Alerts (Metadata API package) | `WorkflowAlert.template` references switched to new template fullnames |
| Updated Flows | Send Email actions repointed to new template IDs |
| Updated Apex | `setTemplateId` calls switched to new IDs |
| Visualforce template retention list | Documented set of VF templates kept with rationale |
| Test plan results | Per-alert send test confirming end-to-end rendering and recipient delivery |

---

## 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-monitoring` — 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