Template Directory Structure

An Opterius Mail template is a directory of Blade view files placed inside resources/views/templates/{template-name}/. Only layouts/app.blade.php is required; all other views fall back to the default template if missing.

Full Directory Tree#

resources/views/templates/
└── mytheme/
    ├── layouts/
    │   └── app.blade.php              (REQUIRED — main application shell)
    ├── auth/
    │   ├── login.blade.php            (Login page)
    │   └── 2fa.blade.php              (TOTP two-factor challenge page)
    ├── inbox/
    │   ├── index.blade.php            (Message list / folder view)
    │   └── message.blade.php          (Single message read view)
    ├── compose/
    │   └── index.blade.php            (Compose / reply / forward form)
    ├── contacts/
    │   ├── index.blade.php            (Contacts list)
    │   └── show.blade.php             (Single contact detail view)
    ├── search/
    │   └── index.blade.php            (Search results page)
    ├── settings/
    │   └── index.blade.php            (User settings page)
    └── partials/
        └── folder-icon.blade.php      (SVG icon helper for folder sidebar)

File Descriptions#

layouts/app.blade.php — Required#

The application shell. Every authenticated webmail page is rendered inside this layout. It provides the outer HTML structure, navigation (sidebar folder list, top toolbar), includes CSS and JavaScript, and defines the content area where page views are injected.

Must implement:

• @yield('title') — the page <title> tag value
• @yield('content') — where the page body is rendered
• @stack('scripts') — where page-specific JavaScript is pushed

Must provide access to Alpine.js 3.x, Tailwind CSS 4.x, and any shared JavaScript.

See Layout Contract for full requirements.

auth/login.blade.php#

The webmail login page. Users enter their full email address and password here. If omitted, the default template's login page is used.

Responsibilities:

• Render the login form (POST to /login).
• Display validation errors ($errors).
• Display any flash messages (e.g., "Your session expired").
• Optionally: show SSO link or SAML login button if those integrations are configured.

auth/2fa.blade.php#

The TOTP two-factor authentication challenge page. Shown after a successful password entry when the account has 2FA enabled.

Responsibilities:

• Render a 6-digit code input form (POST to /2fa/verify).
• Display "wrong code" error if verification failed.
• Show a link to recovery codes.

inbox/index.blade.php#

The message list view for a folder. This is the primary view users see after logging in.

Responsibilities:

• Render a table or list of messages with sender, subject, date, and read/unread state.
• Show pagination or infinite scroll controls.
• Provide message action buttons (delete, mark read/unread, move to folder).
• Integrate with Alpine.js for real-time interactions (marking read, bulk select).

Available variables: $messages, $total, $error — see Template Variables Reference.

inbox/message.blade.php#

The single message read view.

Responsibilities:

• Render the message header (From, To, CC, Subject, Date).
• Render $message->body_html in a sandboxed iframe (to prevent CSS/JS injection).
• Provide reply, forward, delete, and move actions.
• Show attachment list and download links when $message->has_attachments is true.
• Handle $message->body_text as fallback when no HTML body is present.

compose/index.blade.php#

The compose/reply/forward form. The same view is used for all three modes; the $mode variable tells the template which mode is active.

Responsibilities:

• Render the TipTap 2.x rich text editor for the message body.
• Provide To, CC, BCC, Subject fields.
• Handle reply and forward pre-population (from $to, $subject, $body).
• Show attachment upload controls.
• Form submits via AJAX (Alpine.js) to prevent page reloads.

contacts/index.blade.php#

The contacts list view.

Responsibilities:

• Display all contacts for the authenticated user ($contacts).
• Search/filter controls.
• Link to individual contact detail pages.
• Add new contact button.

contacts/show.blade.php#

A single contact's detail view.

Responsibilities:

• Display contact fields (name, email addresses, phone, notes).
• Provide edit and delete actions.
• "Compose to this contact" button.

search/index.blade.php#

The search results page, shown after the user submits a search query.

Responsibilities:

• Display the $query in a search bar (populated from the current search).
• Render $results as a message list (same format as inbox).
• Show result count and "no results" state.

settings/index.blade.php#

The webmail user settings page.

Responsibilities:

• Display and allow editing of user preferences ($settings array).
• Sections: account info, password change, 2FA management, display preferences, notification settings.
• Plugin settings sections are injected here by any installed plugins that use the HOOK_SETTINGS hook.

partials/folder-icon.blade.php#

A small partial that renders an appropriate SVG icon for a given IMAP folder name. Used in the sidebar folder list inside layouts/app.blade.php.

Called with:

@include('templates.mytheme.partials.folder-icon', ['folder' => $folderName])

Maps folder names (INBOX, Sent, Drafts, Trash, Spam, or custom) to icon SVGs. If omitted, the default template's folder icons are used.