1. Overview

WHMS uses a template-based email system. Email templates are stored in the database and can be managed from the admin panel (Settings > Email Templates). Templates support dynamic variable replacement using @{{variable_name}} syntax. Emails are sent via Laravel's Mail system using the configured mail driver (SMTP, Mailgun, etc.).

2. Architecture

Component	Location	Purpose
EmailTemplate Model	app/Models/EmailTemplate.php	Stores templates with slug, subject, HTML/text body, and variables list
TemplateMail Mailable	app/Mail/TemplateMail.php	Renders and sends emails using a template + variables
NotificationService	app/Services/NotificationService.php	Central service that orchestrates email + database notification + SMS delivery
EmailTemplateController	app/Http/Controllers/Admin/EmailTemplateController.php	Admin CRUD for managing email templates
LogSentEmail Listener	app/Listeners/LogSentEmail.php	Logs all sent emails to ActivityLog

3. Pre-configured Email Templates

Template Slug	Trigger	Description
`invoice-created`	New invoice generated	Notifies client of a new invoice with amount, due date, and payment link
`invoice-paid`	Invoice payment received	Confirms payment received with amount and payment date
`invoice-overdue`	Invoice becomes overdue	Alerts client that invoice is past due with balance and days overdue
`invoice-reminder`	Upcoming payment due	Reminds client of upcoming payment (sent at configured intervals before due date)
`invoice-overdue-reminder`	Overdue follow-up	Urgent reminder for overdue invoices (sent at configured intervals after due date)

4. Available Template Variables

Variable	Description	Available In
`@{{client_name}}`	Full name of the client	All templates
`@{{client_first_name}}`	First name of the client	All templates
`@{{invoice_number}}`	Invoice number (e.g. INV-20260414-A1B2C)	All templates
`@{{invoice_total}}`	Total invoice amount	invoice-created, invoice-paid
`@{{invoice_balance}}`	Remaining balance due	invoice-overdue, reminders
`@{{invoice_due_date}}`	Due date formatted	All templates
`@{{invoice_url}}`	Link to view invoice in client portal	All templates
`@{{currency}}`	Currency code (e.g. BDT)	All templates
`@{{company_name}}`	Company name from settings	All templates
`@{{paid_at}}`	Payment date/time	invoice-paid
`@{{days_overdue}}`	Number of days past due	invoice-overdue, overdue-reminder
`@{{days_until_due}}`	Days until due date	invoice-reminder
`@{{due_label}}`	Human-readable due status	Reminders (e.g. "due in 3 days")

5. Event-Driven Email Flow

Event	Listener	Email Template
InvoiceCreated	NotifyInvoiceCreated	invoice-created
InvoicePaid	NotifyInvoicePaid	invoice-paid
InvoiceOverdue	NotifyInvoiceOverdue	invoice-overdue
Scheduled Reminder	SendInvoiceReminder	invoice-reminder / invoice-overdue-reminder

All emails are also logged in the Activity Log. Check Admin > Logs > Activity Log and filter by "email_sent" action.

6. Email Configuration

Mail driver settings are configured in the .env file:

MAIL_MAILER - Driver (smtp, mailgun, ses, etc.)
MAIL_HOST - SMTP server hostname
MAIL_PORT - SMTP port (587 for TLS, 465 for SSL)
MAIL_USERNAME / MAIL_PASSWORD - SMTP credentials
MAIL_FROM_ADDRESS / MAIL_FROM_NAME - Default sender