Admin

Switching Templates

Change the webmail UI theme by setting MAIL_UI_TEMPLATE in your .env and clearing the view cache.

Last updated 2026-04-12

Switching Templates

Opterius Mail's webmail interface is fully themeable through its template system. Templates are directories of Blade views that control the look and layout of the webmail UI. Switching to a different template is a single .env change.

Setting the Active Template

Open /opt/opterius-mail/.env and set:

MAIL_UI_TEMPLATE=minimal

Replace minimal with the name of the template you want to use. The value must match a directory name under resources/views/templates/.

The default template is used when:

  • MAIL_UI_TEMPLATE is not set.
  • The value is set to default.
  • The named template directory does not exist.

Available Templates

Template name Description
default The standard Opterius Mail interface — sidebar navigation, full feature set
minimal Reduced-chrome interface suitable for embedded or kiosk use
(your custom name) Any directory placed in resources/views/templates/

Third-party templates distributed as packages are placed in the same directory and activated by name.

Applying the Change in Production

After editing .env, clear the compiled view cache so Laravel picks up the new template:

cd /opt/opterius-mail
php artisan view:clear
php artisan config:clear

In local/development mode (APP_ENV=local), view caching is disabled and the change takes effect immediately without clearing the cache.

If you are using OPcache, also clear it:

php artisan opcache:clear 2>/dev/null || true

Then reload PHP-FPM:

sudo systemctl reload php8.2-fpm

How the Template System Works

The mailView() helper function is used throughout controllers instead of the standard view() function. It works like this:

// Internal logic of mailView('inbox.index', $data)
// 1. Check for: resources/views/templates/{MAIL_UI_TEMPLATE}/inbox/index.blade.php
// 2. If not found, fall back to: resources/views/templates/default/inbox/index.blade.php

This fallback mechanism means partial templates work. A theme only needs to override the views it wants to change. If inbox/index.blade.php does not exist in your custom template directory, users see the default template's inbox view. Only the views that exist in your template directory will actually be used.

The single required file is layouts/app.blade.php — the main application chrome. All other views are optional.

Template Scope

The template system applies to the webmail interface only (routes under /).

The admin panel at /admin always uses the built-in admin layout (resources/views/admin/layouts/app.blade.php) and is not affected by MAIL_UI_TEMPLATE. You cannot theme the admin panel using this mechanism.

Third-Party Templates

To install a third-party template:

  1. Download the template (e.g., as a ZIP or from a GitHub repository).
  2. Extract it to resources/views/templates/{template-name}/.
  3. Verify the directory contains at least layouts/app.blade.php.
  4. Set MAIL_UI_TEMPLATE={template-name} in .env.
  5. Run php artisan view:clear.
# Example: installing a template called "aurora"
cd /opt/opterius-mail
unzip aurora-template.zip -d resources/views/templates/aurora/
echo "MAIL_UI_TEMPLATE=aurora" >> .env
php artisan view:clear

Reverting to Default

To revert to the default template, either:

MAIL_UI_TEMPLATE=default

Or remove the key entirely:

# Remove the line from .env
sed -i '/^MAIL_UI_TEMPLATE=/d' .env

php artisan view:clear

Building a Custom Template

See Creating a Minimal Template for a step-by-step guide to building your own theme from scratch.

Next
Template Directory Structure →