Email editor broken with FSE / block themes

[polevaultweb]

Bug Report

Description

The email content editor does not work when an FSE (Full Site Editing / block) theme is active. When visiting the email customizer:

• The TinyMCE toolbar never loads — only a plain textarea is shown
• Typing in the textarea has no effect (changes are not saved/previewed)
• The live preview pane does not load correctly

Reported by a user on the WordPress.org support forum: https://wordpress.org/support/topic/no-email-customization-in-fse-theme/

Steps to Reproduce

1. Activate any block/FSE theme (e.g. Twenty Twenty-Three, Twenty Twenty-Four)
2. Go to Users → Emails
3. Click Customize on any email
4. The Customizer opens but the editor panel is broken — no TinyMCE toolbar, no live preview, changes don't save

Root Cause

The email editor is built entirely on top of the WordPress Customizer (customize.php). There are three layers of incompatibility with FSE themes:

1. Customizer preview iframe is broken with block themes. FSE themes do not support the Customizer preview mechanism. WordPress itself has been deprecating Customizer support for block themes since WP 5.9.

2. postMessage transport silently fails. All three email settings (subject, title, content) use transport: postMessage. This relies on a working Customizer preview iframe to relay changes in real time. With FSE, the iframe doesn't load so changes never propagate.

3. TinyMCE doesn't initialize in the Customizer on FSE themes. wp_enqueue_editor() is called in customize_controls_enqueue_scripts and wp.editor.initialize() is called on button click. With FSE themes, TinyMCE is not available in this context (WordPress has been progressively removing TinyMCE from block-theme admin contexts).

Affected Files

• includes/emails/class-wpum-emails-customizer.php — registers all Customizer panels/settings
• includes/emails/class-wpum-emails-customizer-scripts.php — enqueues TinyMCE + JS
• includes/emails/class-wpum-emails-customizer-editor-control.php — custom WP_Customize_Control for the editor
• assets/js/src/admin/admin-email-customizer-controls.js — JS that calls wp.editor.initialize()
• src/emails-list.vue — generates the customize.php?... URL for the Customize button

---

Options for Fix

Option A: Replace Customizer with a standalone admin page (recommended)

Replace customize.php with a dedicated admin subpage (admin.php?page=wpum-email-editor&email=<id>).

• Use wp_editor() directly on the admin page — works with all themes, no Customizer dependency
• Save via AJAX to the same wpum_email option (backward compatible, no data migration)
• Preview can be a non-live iframe (or a "Preview" button opening a new tab) showing the existing email-customizer-preview template
• Change getCustomizationURL() in emails-list.vue to point to the new page

Pros: Theme-agnostic, simpler, no Customizer dependency, wp_editor() is reliable in all admin contexts
Cons: Loses real-time live preview; more UI work needed

Backward compat: The wpum_email option format stays identical. Existing saved email content is preserved. The Customizer code can remain in place (deprecated) for any third-party integrations.

---

Option B: Keep the Customizer, fix TinyMCE + transport

Detect if a block theme is active (wp_is_block_theme(), available since WP 5.9) and conditionally:

• Force-enqueue TinyMCE in the Customizer context
• Switch content transport from postMessage to refresh

Pros: Minimal code change
Cons: The Customizer live preview is fundamentally broken with FSE themes regardless of TinyMCE — refresh transport reloads the iframe which still may not load. Treating symptoms rather than the root cause. Likely to break again with future WordPress versions as the Customizer continues to be deprecated for block themes.

---

Option C: Gutenberg-native editor panel

Build the email editor UI as a React component using @wordpress/components, embedded in a standalone admin page.

Pros: Fully modern, future-proof, consistent with block editor UX
Cons: Significant rewrite; likely out of scope for a bug fix

---

Notes

• Workaround for users: Switch to a classic theme (e.g. Twenty Twenty-One) to use the email editor
• Option A is the recommended path — it resolves the root cause cleanly and keeps backward compatibility
• Still need to assess: whether to keep the Customizer code as a fallback, or remove it entirely once the new page is in place

[polevaultweb]

🔍 Issue Triage

Type: bug
Severity: high
Complexity: large
RICE Score: 3000 — Reach: 3000 × Impact: 2 × Confidence: 100% / Effort: 2pw

---

Problem

The WPUM email customizer is built entirely on top of the WordPress Customizer (customize.php), which is fundamentally incompatible with FSE (Full Site Editing) / block themes. Since WordPress 5.9, FSE themes have progressively removed Customizer support — the preview iframe fails to load, TinyMCE is unavailable in that context, and the postMessage transport for real-time preview silently fails. This means any site running a modern block theme (Twenty Twenty-Three, Twenty Twenty-Four, and any third-party FSE theme) cannot use the email editor at all.

This is a growing problem: block themes now represent the majority of new WordPress theme installs and are the WordPress.org recommended default. As more WPUM customers migrate to block themes, the email editor becomes completely inaccessible. The only current workaround is to switch to a classic theme to customise emails, which is unacceptable for most users.

---

Reproduction Steps

Environment:

• WordPress 6.x with any FSE/block theme active (e.g. Twenty Twenty-Three, Twenty Twenty-Four)
• WPUM 2.9.x
• PHP 8.x

Steps:

1. Activate any block/FSE theme (e.g. Twenty Twenty-Three or Twenty Twenty-Four)
2. Go to Users → Emails in the WP admin
3. Click Customize on any email template
4. The Customizer opens — observe:
   • No TinyMCE toolbar loads (plain textarea only)
   • Typing in the textarea has no effect
   • The live preview pane does not load / shows a blank iframe
   • Changes cannot be saved

Expected: A fully functional email editor that works regardless of the active theme.

Recommended Fix (Option A — standalone admin page):
Replace customize.php with a dedicated admin subpage (admin.php?page=wpum-email-editor&email=<id>):

• Use wp_editor() directly on the admin page (works in all themes, no Customizer dependency)
• Save via AJAX to the same wpum_email option (backward compatible — no data migration needed)
• Preview via a non-live iframe or "Preview" button opening a new tab
• Update getCustomizationURL() in emails-list.vue to point to the new page

---

Acceptance Criteria

• GIVEN an FSE/block theme is active, WHEN an admin visits Users → Emails and clicks Customize, THEN a functional email editor page loads (not the Customizer)
• GIVEN the new email editor, WHEN an admin edits the email subject, title, or content, THEN changes are saved and persist after page reload
• GIVEN the new email editor, WHEN an admin previews the email, THEN a rendered preview of the email template is shown
• GIVEN a classic theme is active, WHEN an admin accesses the email editor, THEN the experience is equivalent (no regression)
• GIVEN existing saved email content, WHEN the new editor is in place, THEN all previously customised email content is preserved (no data migration needed)

---

Technical Notes

• Files involved:
  • includes/emails/class-wpum-emails-customizer.php — registers Customizer panels/settings (to be replaced/deprecated)
  • includes/emails/class-wpum-emails-customizer-scripts.php — enqueues TinyMCE + JS (to be replaced)
  • includes/emails/class-wpum-emails-customizer-editor-control.php — custom WP_Customize_Control (to be replaced)
  • assets/js/src/admin/admin-email-customizer-controls.js — calls wp.editor.initialize() (to be replaced)
  • src/emails-list.vue — generates the customize.php?... URL (update to new admin page URL)
• Dependencies: WordPress wp_editor() API, existing wpum_email option format (unchanged)
• Sensitive areas: None — admin-only feature, no auth or payment touch points
• Estimated effort: Large (~2 person-weeks). Building a new standalone admin page editor to replace the Customizer requires new UI, AJAX save handlers, and preview mechanism. The existing Customizer code can remain temporarily as deprecated fallback.

---

Related Issues

• No direct duplicates found. Linked WordPress.org support topic: https://wordpress.org/support/topic/no-email-customization-in-fse-theme/

---

Backlog summary: [RICE: 3000] [Type: bug] [Effort: L] — Email editor completely broken with FSE/block themes; requires replacing Customizer with standalone admin page