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.

Outbound doctrine: a mail provider is the assumed path. All outbound mail — transactional, composed, and forwarded — leaves through a configured provider (Mailgun, SMTP relay/submission, SES, a connected account). Self-hosting inbound (running your own MX) does not imply self-hosting outbound: a box that receives its own mail still sends through a provider by default. Direct-to-recipient delivery from the box's own port 25 is an advanced setup a user must deliberately pursue — it requires provider-level unblocking of outbound port 25 (most clouds block it by default and lift it only by support ticket), a matching PTR, and owning the IP's sending reputation. Setup flows, health checks, and dashboards treat the provider path as normal and must not present direct self-hosted delivery as a required step or a default fork.

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

Protected identity domains. A From address at a domain the Mailbox plugin marks as a protected sending identity is usable only through the session-gated mailbox compose path (MailboxSender, which sends with an injected transport). For such a domain, OutboundTransport::forHostedAlias() resolves an SmtpProvider on the box's own SMTP submission coordinates — protected mail rides the box's SMTP path, never the ambient platform provider. EmailSender::send() and sendBatch() refuse any transactional (no injected transport) send from such a domain, and SmtpProvider DKIM-signs it in-app with a key unwrapped only inside an open vault unlock window and zeroized after the send. Transactional and notification mail therefore sends from the platform's ordinary domain (or an automated sending subdomain), never a protected identity domain. Core send code consults MailIdentityGuard; the mailbox plugin registers the predicate and signer. See Mailbox Plugin → Outbound send protection.

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]"

Dry Run:

email_dry_run = "1"           // Build and validate, never transmit

EmailSender::send() returns success without touching a transport and without queueing. The check sits after validation, so a malformed message still fails loudly, and above both transport branches, so an injected per-mailbox transport is suppressed along with the globally selected service. Suppressed sends are recorded through the debug log with the service name dry-run.

This is what a test suite sets when the code under test sends mail as a side effect — registration and password reset both do — so a gate run cannot emit real mail through whatever provider the environment happens to point at.

Testing and Debugging

Email Testing System

Email coverage lives in tests/email/ as standard harness tests — run from the unified dashboard at /tests/ or the CLI (php tests/run.php <tier>); see 📖 Testing for tiers and the runner. Each test declares its own tier so the safe/db parts stay in the pre-deploy gate and only the real-mail and real-DNS parts are gated to live:

• email_template_render (db) — template → EmailMessage rendering: variable substitution, subject extraction, subject override, the plain-text alternate, and fail-loud on a missing template. Uses throwaway templates it creates.
• email_provider_config (safe) — the provider registry and per-provider config well-formedness (an unconfigured provider SKIPs, never fails).
• email_send_delivery (live) — closed-loop delivery: sends through the active provider and the SMTP fallback to a throwaway inbound alias, then polls iem_inbound_email_messages to prove the mail actually arrived.
• email_auth_dns (live/prod-verify) — SPF, DKIM, and DMARC against the real published DNS for the configured mailgun_domain.
• email_pattern_send (live) — Mailgun send patterns through EmailSender.
• email_template_iteration (safe) — {loop X as Y} template iteration.

The email pattern test (tests/email/email_pattern_test.php) resolves its recipient in order: the first non-flag command-line argument, then the email_test_recipient setting, then a [email protected] placeholder — so it never sends to a runner flag such as --json.

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.

class SendGridProvider implements EmailServiceProvider {
    public static function getKey(): string { return 'sendgrid'; }
    public static function getLabel(): string { return 'SendGrid'; }
    public static function getSpfMechanism(string $domain): string { return 'include:sendgrid.net'; }
    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.

The structured-only providers (postmark, sendgrid, brevo, mailjet, resend) deliberately do not implement it — they expose no faithful raw-MIME relay. A provider without the capability is detected via instanceof RawMessageRelay (forwarding) or instanceof ApiSubmissionRelay (compose); forwarding falls back to an SMTP relay, and the compose path refuses a non-API provider with a message pointing to an API provider or the relay smarthost. See Mailbox — Forwarding relay and Mailbox — Outbound sending for how the mailbox plugin resolves each path.

Provider DKIM records (optional capability)

DkimRecordSource is a further opt-in capability declared in the same file: a provider that DKIM-signs outbound mail itself implements it to report, from its own API, the DNS records a sending domain must publish for that signing to verify and align:

public static function getDkimStatus(string $domain): array
// ['status' => 'ok'|'not_registered'|'unreachable',
//  'records' => [['type' => ..., 'name' => ..., 'value' => ...], ...]]

ok lists what must be published (possibly nothing left); not_registered means the API answered and the domain is not a sending domain there — the fix is at the provider dashboard, not in DNS; unreachable means callers must render an unknown verdict, never a fabricated one.

Implementers: Mailgun (sending DNS records from the domains API — the _domainkey TXT rows) and SES (Easy DKIM CNAME tokens from GetEmailIdentity; a BYODKIM identity has no tokens and reports ok with no records). Local-submission providers (postfix, smtp) never implement it — opendkim owns their signing. The mailbox Setup tab consumes this to drive its per-domain DKIM rows; see Mailbox — opendkim.

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.