Email System Documentation

Overview

The email system consists of three focused classes that provide clear separation of concerns:

• EmailMessage: Fluent API for composing email messages
• EmailTemplate: Template processing (conditionals, variables)
• EmailSender: All sending logic with service selection and fallback

Inbound transports. Mail can arrive three ways: a self-hosted Postfix MX→pipe, a webhook provider (Mailgun), or by IMAP poll of an existing mailbox (Gmail, Microsoft 365, Yahoo, iCloud, Fastmail, any IMAP host). The first two are push; IMAP is pull — a scheduled task polls the mailbox and ingests new mail. Combined with the generic SMTP outbound provider, IMAP-in gives a complete bring-your-own-mailbox pairing (SMTP out + IMAP in on the same account) for low-volume users with no self-hosted MX. See Receiving by IMAP poll.

Architecture

EmailMessage Class

A clean, fluent API for email composition:

// Create from template
$message = EmailMessage::fromTemplate('activation_content', [
    'act_code' => 'ABC123',
    'resend' => false,
    'recipient' => $user->export_as_array()
]);
$message->from('[email protected]', 'Admin')
        ->to('[email protected]', 'John Doe')
        ->subject('Activate Your Account');

// Create manually
$message = EmailMessage::create('[email protected]', 'Subject', 'Body content')
                       ->from('[email protected]');

Key Methods:

• fromTemplate($name, $values) - Create from database template
• create($to, $subject, $body) - Create simple message
• from($email, $name) - Set sender
• to($email, $name) - Add recipient
• cc($email, $name) - Add CC recipient
• bcc($email, $name) - Add BCC recipient
• subject($subject) - Set subject
• html($content) - Set HTML body
• text($content) - Set plain text body
• attach($path, $name) - Add an on-disk attachment by file path
• attachData($bytes, $name, $contentType) - Add an in-memory attachment (generated/fetched content, no file needed)
• attachInlineData($bytes, $cid, $name, $contentType) - Add an in-memory inline (embedded) image, rendered in the HTML body via a cid: reference (see Inline / embedded images)
• header($name, $value) - Add custom header
• messageId($id) - Pin the outgoing Message-ID (angle-bracketed) instead of letting the transport auto-generate one

EmailSender Class

Handles all sending operations with service selection:

// Send a message
$sender = new EmailSender();
$result = $sender->send($message);

// Quick send (uses default template if HTML detected)
$result = EmailSender::quickSend(
    '[email protected]', 
    'Subject', 
    '<p>HTML content</p>'
);

// Send from template
$result = EmailSender::sendTemplate(
    'welcome_email', 
    '[email protected]',
    ['name' => 'John', 'recipient' => $user->export_as_array()]
);

// Batch send (uses provider's native batch API when available)
$recipients = ['[email protected]', '[email protected]'];
$result = $sender->sendBatch($message, $recipients);
// Returns: ['success' => bool, 'failed_recipients' => string[]]

Service Selection:

• Primary service: email_service setting (mailgun/smtp)
• Fallback service: email_fallback_service setting
• Automatic fallback if primary fails
• Queue failed emails for retry

EmailTemplate Class

Focused on template processing:

// Direct template processing (rarely needed - use EmailMessage instead)
$template = new EmailTemplate('activation_content');
$template->fill_template([
    'act_code' => 'ABC123',
    'resend' => false,
    'recipient' => $user->export_as_array()
]);

// Get processed content
$subject = $template->getSubject();
$html = $template->getHtml();
$text = $template->getText();

Development Patterns

Recommended Approach

// For new code - use EmailMessage + EmailSender
$message = EmailMessage::fromTemplate('welcome_email', [
    'user_name' => $user->get('usr_name'),
    'activation_code' => $code,
    'recipient' => $user->export_as_array()
]);

$message->from('[email protected]', 'Example Site')
        ->to($user->get('usr_email'), $user->get('usr_name'));

$sender = new EmailSender();
$success = $sender->send($message);

Quick Send for Simple Cases

// For simple emails
$success = EmailSender::quickSend(
    $user->get('usr_email'),
    'Welcome to our site!',
    '<h1>Welcome!</h1><p>Thanks for joining us.</p>'
);

Template-based Sending

// When you just need to send a template
$success = EmailSender::sendTemplate(
    'password_reset',
    $user->get('usr_email'),
    [
        'reset_link' => $reset_url,
        'user_name' => $user->get('usr_name'),
        'recipient' => $user->export_as_array()
    ]
);

Template System

Template Processing

Templates support full conditional and variable processing:

Template Structure:

subject:Welcome to *company_name*, *recipient->usr_first_name*!

{~resend}
<h1>Welcome!</h1>
<p>Thanks for signing up on *company_name*! Please click this link to verify:</p>
{end}

{resend}
<p>Please click the following link to verify your email address:</p>
{end}

<p><a href="*web_dir*/activate?code=*act_code*">Activate Account</a></p>

Variable Syntax

• Variables: *variable_name*
• Object access: *recipient->usr_first_name*
• Pipe qualifiers: *date|Y-m-d*
• UTM tracking: *email_vars*

Conditional Syntax

Basic conditionals:

{variable_name}
Content if variable is truthy
{end}

{~variable_name}
Content if variable is falsy (NOT)
{end}

Complex conditionals:

{recipient->usr_level >= 5}
<p>Admin content</p>
{end}

{template_name == "welcome"}
<p>Welcome-specific content</p>
{end}

Variable operations:

{condition}
[counter=1]
[email_type="notification"]  
Content here
{end}

Iteration Syntax

Loop over an array with {loop array_path as item_name} ... {end}:

{loop line_items as line}
- *line->product_name* x*line->quantity*
{end}

The array_path follows the same dot/arrow resolution as variables (e.g. order->items reaches $values['order']['items']). Inside the loop body the loop variable is in scope as a regular value: *item_name*, *item_name->property*, and conditionals like {item_name->is_gift} all work.

Nesting: loops nest with each other and with conditionals in any order. Each iteration runs the full loops -> conditionals -> variables pipeline on its body, so an inner loop sees the outer loop's iteration variable, and a conditional inside a loop sees the loop variable.

{loop groups as group}
*group->name*:
{loop group->members as m}
- *m->name* {m->is_admin}(admin){end}
{end}
{end}

Edge cases (lenient): missing keys, non-array values, and empty arrays all render the loop body zero times with no error.

Caveats

• _expand_loops runs before conditionals, so a loop cannot reference a variable set inside a [var="..."] operation block — by the time conditionals execute, the loop has already expanded.
• The {loop ... } directive must not contain } inside it.
• Templates without any {loop marker bypass the loop pre-pass entirely; rendering behaviour is unchanged from pre-2026 templates.

Subject Processing

Three ways to set subject (priority order):

1. Direct assignment (highest priority):

      $message->subject('Custom Subject');

1. Template subject line:

      subject:Welcome to *company_name*!
      <p>Email body...</p>

1. Template variable:

      subject:*subject*
      <p>Email body...</p>

Bulk Email Recipient Targeting (Recipient-Group Providers)

Admin bulk emails target recipient groups: each targeting row (erg_email_recipient_groups) stores a provider key (erg_provider) plus a reference id (erg_reference_id), with an add/remove direction. The final recipient list is (union of all add groups) minus (union of all remove groups), deduplicated at queue time.

Providers are the pluggable half — includes/RecipientGroupProviderRegistry.php defines the RecipientGroupProvider interface:

To add a targeting source, implement the interface and call RecipientGroupProviderRegistry::register(new YourProvider()) — from registerCoreDefaults() for core, or from your plugin's serve.php.

Service Configuration

Email Services

Mailgun Configuration:

// Settings
mailgun_api_key = "key-abc123..."
mailgun_domain = "mg.example.com"
mailgun_eu_api_link = "https://api.eu.mailgun.net"  // EU endpoint (optional)

SMTP Configuration:

// Settings  
smtp_host = "smtp.example.com"
smtp_port = 587
smtp_username = "[email protected]"
smtp_password = "password"
smtp_encryption = "tls"  // or "ssl"

Service Selection:

// Primary service
email_service = "mailgun"  // or "smtp"

// Fallback service  
email_fallback_service = "smtp"  // or "mailgun"

// Default template for HTML emails
default_email_template = "default_outer_template"

Debug and Testing

Debug Mode:

email_debug_mode = "1"  // Enable debug logging to debug_email_logs table

Test Mode:

email_test_mode = "1"         // Redirect all emails to test address
email_test_redirect = "[email protected]"

Testing and Debugging

Email Testing System

The email suites run from the unified test dashboard at /tests/ and on the CLI through tests/email/email_suite_test.php — see 📖 Testing for tiers, the runner, and how to run. The suites send real mail, so they carry tier live / env prod-verify.

Test Types:

• ServiceTests: SMTP/Mailgun configuration validation
• TemplateTests: Template processing and variable replacement
• DeliveryTests: End-to-end sending simulation (test mode)

Debug Tools

Debug Logging:

// Enable in settings
email_debug_mode = "1"

// View logs
SELECT * FROM debug_email_logs ORDER BY del_timestamp DESC;

Service Validation:

// Check service configuration
$validation = EmailSender::validateService('mailgun');
if (!$validation['valid']) {
    foreach ($validation['errors'] as $error) {
        echo "Error: $error\n";
    }
}

Template Testing:

// Test template without sending
$message = EmailMessage::fromTemplate('test_template', [
    'variable' => 'value',
    'recipient' => $user->export_as_array()
]);

echo "Subject: " . $message->getSubject() . "\n";
echo "HTML Length: " . strlen($message->getHtmlBody()) . "\n";
echo "Ready to send: " . ($message->getSubject() ? 'Yes' : 'No') . "\n";

Advanced Features

Service Fallback

Automatic failover between email services:

// If Mailgun fails, automatically tries SMTP
$sender = new EmailSender();
$success = $sender->send($message);

// Check what actually happened
if ($success) {
    // Email sent successfully (primary or fallback)
} else {
    // Both services failed - email queued for retry
}

Failed Email Queue

Failed emails are automatically queued:

// Failed emails go to queued_email table
// Can be retried later with queue processing script

Custom Headers and Attachments

$message = EmailMessage::create('[email protected]', 'Subject', 'Body')
    ->header('X-Custom-Header', 'value')
    ->attachment('/path/to/file.pdf', 'document.pdf')
    ->replyTo('[email protected]');

Inline / embedded images

An HTML email shows an image two ways: link to it over the web, or *embed the bytes inside the message and reference them from the body with cid:<id> (a Content-ID). Embedding is what makes a logo, chart, or a forwarded inline picture appear in the recipient's client with no network fetch and no login — the right choice for outgoing mail, whose recipient is external and unauthenticated (a hosted /uploads/* URL would give them a broken image or an auth wall).

Add one with attachInlineData(); the body references it by the same bare id:

$message = (new EmailMessage())
    ->to('[email protected]')
    ->subject('Welcome')
    ->html('<p>Hello!</p><img src="cid:logo">')
    ->attachInlineData($logoBytes, 'logo', 'logo.png', 'image/png');

The Content-ID is a bare token — pass logo, not <logo>; the body writes cid:logo. A regular attach() / attachData() entry (no cid) is unchanged and goes out as a normal downloadable attachment.

Per-transport support. Each transport maps inline to its native mechanism. The SMTP path (PHPMailer's embedded-image support) covers the SMTP, connected-account, and SES transports from one place.

// All template variables work
$message = EmailMessage::fromTemplate('template', [
    'recipient' => $user->export_as_array(),  // User data
    'act_code' => $activation_code,           // Custom variables
    'utm_source' => 'newsletter'              // Tracking
]);

// Template can use:
// *recipient->usr_first_name*
// *act_code*
// *web_dir*
// *email_vars* (includes UTM tracking)

$message = EmailMessage::fromTemplate('newsletter', [
    'content' => $newsletter_content
]);

$recipients = [];
$users = new MultiUser(['usr_active' => 1]);
$users->load();
foreach ($users as $user) {
    $recipients[] = $user->get('usr_email');
}

$sender = new EmailSender();
$result = $sender->sendBatch($message, $recipients);
// $result['success'] — true if all recipients succeeded
// $result['failed_recipients'] — array of email addresses that failed
// Failed recipients are automatically retried via the fallback provider,
// then queued for later retry if both providers fail.

try {
    $message = EmailMessage::fromTemplate('template_name', $values);
    $sender = new EmailSender();
    $success = $sender->send($message);
    
    if (!$success) {
        // Email queued for retry
        error_log("Email queued due to service failure");
    }
} catch (EmailTemplateError $e) {
    // Template issue
    error_log("Template error: " . $e->getMessage());
} catch (Exception $e) {
    // Other issues
    error_log("Email error: " . $e->getMessage());
}

// CORRECT - includes recipient data
$success = EmailSender::sendTemplate('welcome', 
    $user->get('usr_email'),
    [
        'activation_code' => $code,
        'recipient' => $user->export_as_array()  // Required for templates
    ]
);

// MISSING - may cause template variable errors
$success = EmailSender::sendTemplate('welcome', 
    $user->get('usr_email'),
    ['activation_code' => $code]  // Missing recipient data
);

> Record presence ≠ message verification. DnsAuthChecker is a DNS > record check — it inspects domains we control for a sane outbound/setup > config. It is not verification of an inbound message's connecting IP > against a record, and must never be repurposed for inbound verdicts. The app > does not compute inbound SPF/DKIM/DMARC at all. Per-inbound-message > verdicts come from the message's Authentication-Results header, stamped by > the verifying MTA (opendkim-verify + opendmarc) and read by the mailbox > plugin's AuthenticationResults/InboundEmailRouter — never from > DnsAuthChecker. See plugins/mailbox/docs/overview.md → > Inbound authentication*.

require_once(PathHelper::getIncludePath('includes/DnsAuthChecker.php'));

$spf = DnsAuthChecker::checkSPF('example.com');   // ['status'=>'pass|warn|fail', 'detail'=>…, 'record'=>…]
$all = DnsAuthChecker::quickCheck('example.com'); // ['spf'=>…, 'dkim'=>…, 'dmarc'=>…]

Its lookups go through DnsResolver (the platform's single raw-DNS chokepoint — see Validation › DNS Lookups), so a resolver failure is handled cleanly and the checks are unit-testable via DnsResolver::setBackend(). DnsAuthChecker's own public static API is unchanged by that — callers and the EmailAuthChecker subclass are unaffected.

Email Service Provider Interface

The email system uses a provider abstraction so that new email services can be added without modifying core code.

Architecture

• EmailServiceProvider — interface in includes/EmailServiceProvider.php that all outbound providers implement
• InboundEmailProvider — sibling interface in includes/InboundEmailProvider.php for inbound transports (Postfix, Mailgun webhook, etc.). A single provider class may implement both interfaces; the Mailbox plugin discovers inbound providers via InboundProviderRegistry. See Mailbox Plugin for the inbound side.
• RawMessageRelay — optional capability interface, declared alongside EmailServiceProvider in includes/EmailServiceProvider.php. A provider opts in to relay raw MIME with a chosen envelope sender; used by inbound-email forwarding. See Raw-MIME relay below.
• Provider classes — live in includes/email_providers/ (e.g., MailgunProvider.php, SmtpProvider.php, SendGridProvider.php)
• Auto-discovery — EmailSender scans includes/email_providers/ for classes implementing EmailServiceProvider; InboundProviderRegistry walks the same directory for classes implementing InboundEmailProvider. No manual registration needed in either case.

Built-in Providers

Adding a New Provider

Create a single file in includes/email_providers/ implementing EmailServiceProvider:

class SendGridProvider implements EmailServiceProvider {
    public static function getKey(): string { return 'sendgrid'; }
    public static function getLabel(): string { return 'SendGrid'; }
    public static function getSettingsFields(): array { /* ... */ }
    public static function validateConfiguration(): array { /* ... */ }
    public function send(EmailMessage $message): bool { /* ... */ }
    public function sendBatch(EmailMessage $message, array $recipients): array { /* ... */ }
}

The provider automatically appears in the admin email settings dropdown and its configuration fields render dynamically. No other files need modification.

Interface Methods

Raw-MIME relay (optional capability)

RawMessageRelay is an opt-in capability interface declared next to EmailServiceProvider in includes/EmailServiceProvider.php (no separate file — it is in scope wherever providers are resolved). A provider implements it in addition to EmailServiceProvider when it can relay an already-formed RFC 5322 message byte-for-byte to chosen envelope recipients with an explicit envelope sender (Return-Path / MAIL FROM):

class MailgunProvider implements EmailServiceProvider, InboundEmailProvider, ApiSubmissionRelay {
    // ...
    public function relayRawMessage(string $raw_mime, string $envelope_sender, array $destinations): array {
        // relay $raw_mime as-is to $destinations; returns ['dest@x' => bool]
    }
}

What it is for. The normal send() path rebuilds a message from from/to/subject/html|text and exposes no envelope-sender field, so it cannot relay original MIME faithfully or set a custom Return-Path. Two callers need both:

• Inbound-email forwarding uses RawMessageRelay when the active outbound provider implements it, reusing that provider's existing credential.
• The hidden-origin compose path (RawRelayComposeTransport, on a relay-fronted deployment with the relay smarthost off) builds a fully formed, in-app-signed message and hands it to relayRawMessage() so the sent message's Received: chain begins inside the provider and the main box IP is never exposed. This path requires ApiSubmissionRelay — a sub-interface a provider adds to self-declare that it submits over an HTTP API, not SMTP. SMTP submission stamps the connecting client's IP into the first Received: header, so SmtpProvider implements RawMessageRelay but not ApiSubmissionRelay and is excluded from the compose path.

Protected-domain From addresses remain usable only via the session-gated mailbox compose path (the injected transport), never by transactional senders — whether that transport submits directly, through the relay smarthost, or through the provider's raw-MIME API.