Email Templates (Developer Track)

The Preads Platform uses a centralized, database-driven email template system. This guide explains how to technically customize templates, manage variables, and implement new automated notifications.

⚙️ Rendering Engine

The platform employs a lightweight placeholder replacement engine (instead of standard Blade for database content) to ensure security and administrative flexibility.

Placeholder Syntax

All variables must be enclosed in curly braces: {variable_name}. When a template is rendered, the system performs a recursive search-and-replace using an associative array of data.

// Internal logic in EmailTemplate.php
protected function replaceVariables(string $text, array $data): string
{
    foreach ($data as $key => $value) {
        $text = str_replace('{' . $key . '}', (string) $value, $text);
    }
    return $text;
}

🏠 The Master Template

The Master Template (slug: master) serves as the universal layout for all communications.

Implementation

When EmailService::send() is called:

  1. The specific template (e.g., password_reset) is rendered.
  2. The rendered content is then injected into the Master Template via the {content} variable.
  3. Branding elements (Logo, Footer, Social Links) should be defined centrally in the Master Template to maintain consistency.

📊 Variable Reference

The platform supports three tiers of variables that can be used in any template.

1. Global System Variables

Automatically available in every email sent by the platform.

  • {site_name}: The name of your network.
  • {site_url}: The root domain of the installation.
  • {support_email}: The primary support contact address.
  • {year}: The current calendar year (useful for copyright footers).

2. Custom Global Variables

Administrators can define additional global placeholders in Admin Panel → Settings → Global Variables. These are stored as JSON and merged at runtime.

3. Contextual (Logic-Driven) Variables

These vary depending on the specific event.

  • Auth: {name}, {email}, {verification_url}, {reset_url}.
  • Financial: {amount}, {currency}, {method}, {transaction_id}.
  • System: {reason}, {app_name}, {app_url}.

🚀 Implementing New Notifications

To add a new automated email, follow these two steps:

Step 1: Database Entry

Create a new entry in the email_templates table. It is recommended to use the system category for core notifications.

Step 2: Service Dispatch

Inject the EmailService into your controller or job and call the send method.

use App\Services\EmailService;

public function approveWithdrawal(Withdrawal $withdrawal, EmailService $emailService)
{
    // ... logic ...

    $emailService->send(
        $withdrawal->publisher->email,
        'withdrawal_approved',
        [
            'name' => $withdrawal->publisher->name,
            'amount' => formatCurrency($withdrawal->amount),
            'method' => $withdrawal->method->name,
            'transaction_id' => $withdrawal->transaction_id
        ]
    );
}

🛡️ Best Practices

  • Fallback Content: Always ensure your templates have a plain-text fallback or a well-structured HTML layout to support different mail clients.
  • Safe Reset: If a developer breaks a system template, it can be restored to its default state using the Reset to Default button in the Admin Panel (which re-runs the internal seeder).
  • Validation: When creating new templates via the API or direct DB access, ensure the slug is unique and contains only alphanumeric characters and underscores.

Explore API Documentation →