Reusable HTML Email Templates (WordPress plugin)
Model note: Mechanical refactoring — extract strings, create template files, wire wp_mail(). haiku handles end-to-end.
Move email bodies out of inline PHP strings into templates/emails/, where every message reuses one branded shell. Adding a new email = adding one content file.
When to use
- "Move email content to templates", "branded/HTML emails", "reuse an email template".
- Any plugin building messages inline with
wp_mail() heredocs.
Not for: REST API webhooks, push notifications, or Slack integrations. Transactional email in themes — this skill targets plugin-delivered mail only.
Structure
templates/emails/
base.php shared shell: header, body slot ($content), footer
<name>.php per-email content (greeting, copy, CTA button)
- base.php — table-based, inline-CSS responsive shell (email clients ignore
<style>/external CSS). Receives $subject, $preheader, $content, $site_name, $site_url. Echoes $content raw (// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped — content templates escape their own values).
- content templates — escape every variable (
esc_html, esc_url); wrap copy in __()/esc_html__() with the text domain; use _n() for plurals. Guard each $var = $var ?? default; so the file is robust if rendered standalone.
Render helpers (in your Helpers class)
public static function render_template( string $path, array $vars = [] ): string {
if ( ! is_readable( $path ) ) return '';
// phpcs:ignore WordPress.PHP.DontExtract.extract_extract -- controlled template vars
extract( $vars, EXTR_SKIP );
ob_start();
include $path;
return (string) ob_get_clean();
}
public static function render_email( string $template, array $vars = [] ): string {
$dir = (string) plugin_config( 'templates' ) . 'emails/'; // your assets/templates path helper
$vars['content'] = self::render_template( $dir . $template . '.php', $vars );
$vars['site_name'] = $vars['site_name'] ?? get_bloginfo( 'name' );
$vars['site_url'] = $vars['site_url'] ?? home_url( '/' );
return self::render_template( $dir . 'base.php', $vars ); // always wrap in the shell
}
A missing content template yields an empty body but the shell still renders — callers always get a valid document.
Sending
$body = Helpers::render_email( 'welcome', [ 'subject' => $subject, 'user_name' => $u->display_name, ... ] );
$headers = [ 'Content-Type: text/html; charset=UTF-8' ]; // REQUIRED for HTML
return wp_mail( $to, $subject, $body, $headers );
Drive any TTL/expiry copy from the same constant the code uses (e.g. a token transient TTL) so email text can't drift from behavior.
Gotchas
- Entities in translated strings:
© double-escapes through esc_html__ → use the literal ©.
- Don't assign WordPress globals in templates (
$year etc. trip WordPress.WP.GlobalVariablesOverride) — inline gmdate('Y') instead.
Testing
WP's test suite captures wp_mail via MockPHPMailer:
reset_phpmailer_instance();
// ... trigger the send ...
$sent = tests_retrieve_phpmailer_instance()->get_sent();
$this->assertStringContainsString( 'text/html', $sent->header );
$this->assertStringContainsString( '<!DOCTYPE html', $sent->body ); // base shell used
$this->assertStringContainsString( $expected_cta, $sent->body );
Force a send failure with add_filter( 'pre_wp_mail', '__return_false' ) to test the error branch.
References
references/base.php — the full responsive HTML base shell (header/body/footer, inline CSS), copy into templates/emails/base.php.references/content-example.php — an example content template (greeting, CTA button, optional expiry, fallback link) to copy and adapt per email.references/html-email-patterns.md — HTML email patterns: table-based layout rules, inline CSS requirements, dark-mode support, and Outlook-specific fixesreferences/wp-mail-api.md — WordPress mail API reference: wp_mail() parameters, phpmailer_init hook, SMTP configuration, and deliverability checklist
1---2name: wp-email-templates3description: Use when adding or refactoring transactional emails in a WordPress plugin — extracting inline HTML strings into reusable templates sharing a branded base shell, implementing the render_template helper (ob_start / include / ob_get_clean), passing variables safely with extract(EXTR_SKIP), sending via wp_mail(), testing with MockPHPMailer / tests_retrieve_phpmailer_instance(), applying table-based HTML layout and inline CSS for email clients, or handling wp_mail send-failure branches. Triggers: "send an email from my plugin", "wp_mail not working", "add an email template", "style my plugin emails", "HTML email in WordPress", "branded email wrapper", "email not arriving", "test my wp_mail", "add a CTA button to the email", "make emails look good in Outlook", "transactional email template", "render_template helper", "ob_start for email", "extract EXTR_SKIP", "MockPHPMailer in tests", "tests_retrieve_phpmailer_instance", "pre_wp_mail filter to test failure", "inline CSS email", "dark mode email support", "table-bas4---56# Reusable HTML Email Templates (WordPress plugin)78> **Model note:** Mechanical refactoring — extract strings, create template files, wire `wp_mail()`. `haiku` handles end-to-end.910Move email bodies out of inline PHP strings into `templates/emails/`, where every message reuses one branded shell. Adding a new email = adding one content file.1112## When to use1314- "Move email content to templates", "branded/HTML emails", "reuse an email template".15- Any plugin building messages inline with `wp_mail()` heredocs.1617**Not for:** REST API webhooks, push notifications, or Slack integrations. Transactional email in themes — this skill targets plugin-delivered mail only.1819## Structure2021```22templates/emails/23 base.php shared shell: header, body slot ($content), footer24 <name>.php per-email content (greeting, copy, CTA button)25```2627- **base.php** — table-based, inline-CSS responsive shell (email clients ignore `<style>`/external CSS). Receives `$subject`, `$preheader`, `$content`, `$site_name`, `$site_url`. Echoes `$content` raw (`// phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped` — content templates escape their own values).28- **content templates** — escape every variable (`esc_html`, `esc_url`); wrap copy in `__()`/`esc_html__()` with the text domain; use `_n()` for plurals. Guard each `$var = $var ?? default;` so the file is robust if rendered standalone.2930## Render helpers (in your Helpers class)3132```php33public static function render_template( string $path, array $vars = [] ): string {34 if ( ! is_readable( $path ) ) return '';35 // phpcs:ignore WordPress.PHP.DontExtract.extract_extract -- controlled template vars36 extract( $vars, EXTR_SKIP );37 ob_start();38 include $path;39 return (string) ob_get_clean();40}4142public static function render_email( string $template, array $vars = [] ): string {43 $dir = (string) plugin_config( 'templates' ) . 'emails/'; // your assets/templates path helper44 $vars['content'] = self::render_template( $dir . $template . '.php', $vars );45 $vars['site_name'] = $vars['site_name'] ?? get_bloginfo( 'name' );46 $vars['site_url'] = $vars['site_url'] ?? home_url( '/' );47 return self::render_template( $dir . 'base.php', $vars ); // always wrap in the shell48}49```5051A missing content template yields an empty body but the shell still renders — callers always get a valid document.5253## Sending5455```php56$body = Helpers::render_email( 'welcome', [ 'subject' => $subject, 'user_name' => $u->display_name, ... ] );57$headers = [ 'Content-Type: text/html; charset=UTF-8' ]; // REQUIRED for HTML58return wp_mail( $to, $subject, $body, $headers );59```6061Drive any TTL/expiry copy from the same constant the code uses (e.g. a token transient TTL) so email text can't drift from behavior.6263## Gotchas6465- Entities in translated strings: `©` double-escapes through `esc_html__` → use the literal `©`.66- Don't assign WordPress globals in templates (`$year` etc. trip `WordPress.WP.GlobalVariablesOverride`) — inline `gmdate('Y')` instead.6768## Testing6970WP's test suite captures `wp_mail` via MockPHPMailer:7172```php73reset_phpmailer_instance();74// ... trigger the send ...75$sent = tests_retrieve_phpmailer_instance()->get_sent();76$this->assertStringContainsString( 'text/html', $sent->header );77$this->assertStringContainsString( '<!DOCTYPE html', $sent->body ); // base shell used78$this->assertStringContainsString( $expected_cta, $sent->body );79```8081Force a send failure with `add_filter( 'pre_wp_mail', '__return_false' )` to test the error branch.8283## References8485- `references/base.php` — the full responsive HTML base shell (header/body/footer, inline CSS), copy into `templates/emails/base.php`.86- `references/content-example.php` — an example content template (greeting, CTA button, optional expiry, fallback link) to copy and adapt per email.87- `references/html-email-patterns.md` — HTML email patterns: table-based layout rules, inline CSS requirements, dark-mode support, and Outlook-specific fixes88- `references/wp-mail-api.md` — WordPress mail API reference: `wp_mail()` parameters, `phpmailer_init` hook, SMTP configuration, and deliverability checklist
mralaminahamed