README

A comprehensive email composition library for WordPress with beautiful responsive templates, component builders, placeholder replacement, and extensive customization options.

Features

📧 Beautiful Templates - 7 responsive, tested email templates
🎨 Component Builder - Tables, buttons, alerts, product lists
🔄 Placeholder System - Dynamic content replacement with {placeholders}
🎯 Theme Override - Custom templates via theme directory
🔧 Fluent Interface - Chainable methods for clean code
🌍 WordPress Native - Uses wp_mail() with proper filters/actions
📱 Mobile Responsive - All templates work across devices
✉️ Email Client Compatible - Tested in Gmail, Outlook, Apple Mail

Installation

composer require arraypress/wp-email-builder

Basic Usage

use ArrayPress\WP\EmailBuilder\Email;

// Simple email
$email = new Email();
$email->to( 'customer@example.com' )
      ->subject( 'Welcome to Our Store' )
      ->content( '<p>Thank you for joining us!</p>' )
      ->send();

// With configuration
$email = new Email([
    'template' => 'modern',
    'logo'     => 'https://example.com/logo.png',
    'colors'   => [
        'primary' => '#0073aa'
    ]
]);

Available Templates

Template	Description	Use Case
`default`	Professional with gradient header	General purpose
`minimal`	Clean, typography-focused	Simple messages
`modern`	Gradient backgrounds, cards	Marketing
`notification`	Alert-style with icon	System notifications
`transaction`	Receipt/invoice style	Orders, receipts
`newsletter`	Editorial/blog style	Content updates
`plain`	Monospace text-like	Technical messages

Adding Components

Tables

$email->add_table([
    ['Product', 'Quantity', 'Price'],
    ['Premium License', '1', '$99.00'],
    ['Support Package', '1', '$49.00'],
    ['Total', '', '$148.00']
], ['total_row' => true]);

Buttons

$email->add_button( 
    'View Order', 
    'https://example.com/order/123',
    ['align' => 'center', 'background' => '#10b981']
);

Alerts

$email->add_alert( 
    'Your subscription expires in 3 days',
    'warning' 
);

Product Lists

$email->add_products([
    [
        'name'        => 'WordPress Plugin',
        'description' => 'Premium features included',
        'price'       => '$99.00',
        'image'       => 'https://example.com/product.jpg'
    ]
]);

Key-Value Lists

$email->add_key_value_list([
    'Order Number'   => '#12345',
    'Date'          => 'Dec 15, 2025',
    'Payment Method' => 'Credit Card',
    'Status'        => 'Processing'
]);

Advanced Configuration

Custom Template Configuration

$email = new Email([
    'template'     => 'modern',
    'logo'         => 'https://example.com/logo.png',
    'logo_height'  => 60,
    'footer_text'  => '© {year} {site_name}. All rights reserved.',
    'social_links' => [
        'Twitter'  => 'https://twitter.com/example',
        'Facebook' => 'https://facebook.com/example',
        'LinkedIn' => 'https://linkedin.com/company/example'
    ],
    'colors' => [
        'primary'    => '#667eea',
        'secondary'  => '#764ba2',
        'success'    => '#10b981',
        'error'      => '#ef4444',
        'warning'    => '#f59e0b',
        'info'       => '#3b82f6',
        'text'       => '#374151',
        'text_muted' => '#6b7280',
        'background' => '#f9fafb',
        'border'     => '#e5e7eb'
    ]
]);

Placeholder Replacement

$email->replacements([
    '{customer_name}' => 'John Doe',
    '{order_id}'     => '12345',
    '{total}'        => '$299.00',
    '{download_url}' => 'https://example.com/download/xyz'
])
->content( 'Hi {customer_name}, your order #{order_id} for {total} is ready!' );

Email Headers

$email->from( 'sales@example.com', 'Sales Team' )
      ->reply_to( 'support@example.com', 'Support' )
      ->cc( 'manager@example.com' )
      ->bcc( 'archive@example.com' );

Attachments

$email->attach( '/path/to/invoice.pdf' )
      ->attach( '/path/to/terms.pdf' );

Plugin Integration Example

class MyPlugin_Emails {
    
    private Email $mailer;
    
    public function __construct() {
        // Configure once with all settings
        $this->mailer = new Email([
            'template'     => get_option( 'email_template', 'default' ),
            'logo'         => get_option( 'email_logo' ),
            'footer_text'  => get_option( 'email_footer' ),
            'social_links' => get_option( 'social_links', [] ),
            'colors'       => [
                'primary' => get_option( 'brand_color', '#667eea' )
            ]
        ]);
    }
    
    public function send_receipt( $order ) {
        $email = clone $this->mailer;
        
        return $email->to( $order->email )
                     ->subject( 'Order Receipt #{order_id}' )
                     ->replacements([
                         '{order_id}'     => $order->id,
                         '{customer_name}' => $order->customer_name,
                         '{total}'        => $order->get_formatted_total()
                     ])
                     ->content( '<p>Thank you for your purchase!</p>' )
                     ->add_table( $order->get_items_for_email() )
                     ->add_button( 'View Order', $order->get_view_url() )
                     ->send();
    }
}

Theme Override

Create custom templates in your theme:

/your-theme/
  /email-builder/
    default.html
    custom-template.html

Then use:

$email->template( 'custom-template' );

Quick Send

For simple one-off emails:

Email::send_quick([
    'to'           => 'user@example.com',
    'subject'      => 'Quick Message',
    'content'      => '<p>Your message here</p>',
    'template'     => 'notification',
    'replacements' => [
        '{name}' => 'John'
    ]
]);

Hooks & Filters

Modify email before sending

add_filter( 'email_builder_before_send', function( $email_data, $context ) {
    // Modify $email_data array
    return $email_data;
}, 10, 2 );

After email sent

add_action( 'email_builder_after_send', function( $sent, $context ) {
    if ( $sent ) {
        // Log successful send
    }
}, 10, 2 );

Custom templates

add_filter( 'email_builder_templates', function( $templates ) {
    $templates['custom'] = file_get_contents( __DIR__ . '/email-template.html' );
    return $templates;
} );

Component Reference

Email Class Methods

Method	Description
`to( $email )`	Set recipient(s)
`subject( $subject )`	Set subject line
`content( $content )`	Set email body
`template( $name )`	Set template
`from( $email, $name )`	Set from address
`reply_to( $email, $name )`	Set reply-to
`cc( $email )`	Add CC recipient
`bcc( $email )`	Add BCC recipient
`attach( $file )`	Add attachment
`replacements( $array )`	Set placeholders
`context( $array )`	Set context for filters
`add_button()`	Add button component
`add_table()`	Add table component
`add_alert()`	Add alert component
`add_divider()`	Add divider
`add_heading()`	Add heading
`add_products()`	Add product list
`add_key_value_list()`	Add key-value pairs
`send()`	Send the email

Components Class Static Methods

Method	Description
`button()`	Create button HTML
`table()`	Create table HTML
`alert()`	Create alert box
`divider()`	Create horizontal rule
`heading()`	Create heading
`product_list()`	Create product grid
`key_value_list()`	Create definition list
`logo()`	Create logo image
`footer()`	Create footer section

arraypress / wp-email-builder

Maintainers

Details