Webmail Client

A full-featured webmail client integrated directly into the Larapen admin panel. Connect any IMAP/SMTP email account and read, compose, reply, forward, and manage messages without leaving your dashboard.

Use Cases

Site Administrator

You manage a Larapen site and want to read and respond to emails (support inquiries, contact form notifications) without switching to a separate email client.

• Add your business email account (e.g. admin@yoursite.com).
• Read incoming messages in the admin panel inbox.
• Reply directly from the dashboard with your email signature.

Multiple Team Accounts

Each admin user manages their own email account(s). A support lead can add both support@company.com and billing@company.com, switching between them as needed.

Centralised Communication

Keep all site-related communication visible in one place. Forward important emails, compose outreach messages, and manage customer correspondence: all from the admin panel.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+ with the imap extension enabled
• MySQL 8.0+ (required for FULLTEXT indexing on the messages table)
• The webklex/php-imap Composer package (included with the add-on)
• An email account with IMAP and SMTP access

Installation

Step 1: Place the Add-on

Copy or symlink the webmail folder into your Larapen "extensions/addons" directory:

Step 2: Activate the Add-on

Go to Admin → Add-ons → Installed Add-ons and activate Webmail Client.

Step 3: Run Migrations

This creates 5 tables: webmail_accounts, webmail_folders, webmail_identities, webmail_messages, and webmail_attachments.

Step 4: Set Permissions

The add-on registers 12 permissions (see Permissions). Assign them to admin roles via Admin → Users → Roles & Permissions.

Step 5: Add an Email Account

Navigate to Admin → Webmail → Accounts and click Add Account. Enter your IMAP and SMTP server details. Use the Test Connection button to verify before saving. See Accounts.

Configuration

Global settings are managed in Admin → Webmail → Settings. The configuration file is config/webmail.php and values can be overridden from the admin panel (stored in the settings table, group webmail).

Setting	Description	Default
local_cache	When enabled, messages are stored in the local database for faster loading. Only new messages are fetched incrementally from the IMAP server.	false
messages_per_page	Number of messages displayed per page in the mailbox view.	25
auto_refresh_interval	Auto-refresh interval in seconds. Set to 0 to disable auto-refresh.	0
max_attachment_size	Maximum attachment size in KB. Default is 25 MB (25600 KB).	25600
attachment_preview	When enabled, previewable attachments (images, PDFs) are opened inline in the browser instead of forcing a download.	true
html_display_mode	How to render HTML emails: iframe (sandboxed) or text (plain text only).	iframe
date_format	PHP date() format string used to display message dates.	M j, g:i A
default_imap_port	Default IMAP port pre-filled when creating a new account.	993
default_imap_encryption	Default IMAP encryption pre-filled when creating a new account.	ssl
default_smtp_port	Default SMTP port pre-filled when creating a new account.	465
default_smtp_encryption	Default SMTP encryption pre-filled when creating a new account.	ssl

Account Management

Each admin user manages their own email accounts. Accounts are scoped to the authenticated user: one user cannot see or modify another user’s accounts.

Adding an Account

Navigate to Admin → Webmail → Accounts → Add Account. The form requires:

Field	Required	Description
name	Yes	Display name for the account (e.g. “Work Email”).
email	Yes	Email address. Must be unique per user.
imap_host	Yes	IMAP server hostname (e.g. imap.gmail.com).
imap_port	Yes	IMAP port (typically 993 for SSL, 143 for STARTTLS).
imap_encryption	Yes	Encryption: ssl, tls, starttls, or none.
imap_username	Yes	IMAP login username (usually the email address).
imap_password	Yes	IMAP password. Encrypted before storage.
imap_validate_cert	No	Validate SSL certificate. Default: true. Disable for self-signed certs.
smtp_host	Yes	SMTP server hostname (e.g. smtp.gmail.com).
smtp_port	Yes	SMTP port (typically 465 for SSL, 587 for STARTTLS).
smtp_encryption	Yes	Encryption: ssl, tls, starttls, or none.
smtp_username	No	SMTP username. Falls back to IMAP username if empty.
smtp_password	No	SMTP password. Falls back to IMAP password if empty. Encrypted before storage.
signature	No	HTML email signature appended to outgoing messages. Max 10,000 characters.
is_active	No	Enable or disable the account. Default: true.
is_default	No	Set as the default account. Only one account per user can be default.

Common IMAP & SMTP Settings

Provider	IMAP Host	IMAP Port	SMTP Host	SMTP Port	Encryption
Gmail	imap.gmail.com	993	smtp.gmail.com	465	SSL
Outlook / Microsoft 365	outlook.office365.com	993	smtp.office365.com	587	STARTTLS
Yahoo Mail	imap.mail.yahoo.com	993	smtp.mail.yahoo.com	465	SSL
Custom / cPanel	mail.yourdomain.com	993	mail.yourdomain.com	465	SSL

Testing the Connection

Click the Test Connection button on the account form to verify IMAP connectivity before saving. The test attempts to connect to the IMAP server with the provided credentials and returns a success or error message. This is an AJAX request: no page reload required.

Inbox & Folders

The main mailbox view is accessible at Admin → Webmail → Inbox. It displays the message list for the selected account and folder.

Account Switching

If a user has multiple accounts, a dropdown allows switching between them. The default account is selected automatically on first load.

Folder Navigation

Folders are synced from the IMAP server automatically. The add-on detects standard folder types:

• Inbox: incoming messages
• Sent: sent messages
• Drafts: draft messages
• Trash: deleted messages
• Spam: spam/junk messages
• Archive: archived messages
• Custom: any other user-created folders

Folder type detection handles Gmail, Outlook, and standard IMAP folder naming conventions. Each folder displays its total and unseen message counts.

Refreshing Folders

Click the Refresh button to re-sync folders from the IMAP server. This updates folder lists, message counts, and (when local caching is enabled) downloads new messages.

Reading Messages

Click any message in the list to view its full content. The message detail view displays:

• From, To, CC, BCC addresses
• Subject and date
• HTML body (rendered in a sandboxed iframe) or plain text body
• Attachment list with download links
• Quick action buttons: Reply, Reply All, Forward, Delete

Search

Use the search bar to find messages within the current folder. When local caching is enabled, search uses MySQL FULLTEXT indexing on the subject and text_body columns, as well as JSON search on address fields. When caching is disabled, search queries the IMAP server directly.

Message Actions

The following actions are available via AJAX (no page reload):

Action	Description
Mark Read	Mark the message as read on the IMAP server.
Mark Unread	Mark the message as unread on the IMAP server.
Star	Flag/star the message.
Unstar	Remove the flag/star from the message.
Delete	Permanently delete the message from the server.
Move to Trash	Move the message to the Trash folder.
Move	Move the message to a different folder.
Spam	Move the message to the Spam folder.

Compose & Reply

New Message

Navigate to Admin → Webmail → Compose to create a new email. Select the sending account (if you have multiple), fill in the To, CC, and BCC fields, enter a subject and message body, and click Send.

• Multiple recipients can be entered as comma-separated addresses.
• CC and BCC fields are hidden by default and can be expanded via toggle links.
• The account’s signature is appended automatically if one is configured.

Reply & Forward

From the message detail view, click Reply, Reply All, or Forward to open the compose form pre-populated with:

• Reply: To field set to the original sender. Subject prefixed with Re:. Original message quoted.
• Reply All: To field set to the original sender plus all CC recipients. Subject prefixed with Re:.
• Forward: To field left empty. Subject prefixed with Fwd:. Original message quoted with forwarded header block.

The quoting format uses the pattern: “On [date], [sender] wrote:” followed by the original message body.

Attachments

Outgoing messages support file attachments. The maximum attachment size is controlled by the max_attachment_size setting (default: 25 MB). Previewable attachments (images, PDFs) can be opened inline in the browser when attachment_preview is enabled.

To download an attachment from a received message, click the attachment name in the message detail view. Attachments are fetched directly from the IMAP server on demand.

Settings

Navigate to Admin → Webmail → Settings to configure the add-on. Settings are organized into sections:

Display

• Messages per page: number of messages shown per page in the mailbox.
• HTML display mode: iframe (sandboxed, recommended) or text (plain text only).
• Date format: PHP date format for message timestamps.
• Attachment preview: open images/PDFs inline or force download.
• Max attachment size: maximum file size for outgoing attachments (in KB).

Performance

• Local cache: enable database-backed message caching for faster loading.
• Auto-refresh interval: automatic mailbox refresh in seconds. Set to 0 to disable, or choose intervals like “on tab focus”, 30 seconds, 1 minute, etc.

Updating

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

Step 3: Clear Caches

Step 4: Verify

Visit Webmail → Accounts and verify that your accounts are still listed and operational. Click Test Connection on an account to confirm connectivity.

Troubleshooting

Test Connection fails: “Could not connect to IMAP server”

Check that:

• The IMAP host and port are correct for your email provider.
• The encryption type matches the port (SSL for 993, STARTTLS for 143).
• The username and password are correct. For Gmail, use an App Password if 2FA is enabled.
• Your server’s firewall allows outbound connections on the IMAP port.
• If using a self-signed certificate, disable imap_validate_cert.

Messages not loading: blank inbox

• Click Refresh to force a folder sync.
• Check that the account is marked as Active.
• Look at the connection_error column in webmail_accounts for stored error messages.
• Verify that the IMAP server allows the connection (some providers require enabling “IMAP access” in their settings).

Sending email fails: “Send failed”

• Verify SMTP host, port, and encryption settings.
• If SMTP username/password are left empty, the system falls back to IMAP credentials: ensure those work for SMTP too.
• Check server logs (storage/logs/laravel.log) for the specific SMTP error message.
• Some providers (e.g. Gmail) require allowing “less secure apps” or using App Passwords.

Folder sync shows wrong folder types

The add-on uses heuristic detection to identify folder types. If a folder is incorrectly categorised (e.g. your “Sent” folder is showing as “custom”), check that:

• The folder name follows standard IMAP conventions for your provider.
• Gmail folders use the [Gmail]/ prefix (e.g. [Gmail]/Sent Mail).
• The resolveCanonicalFolders() method handles duplicate types by selecting the most appropriate one.

Local cache not updating

• Ensure local_cache is set to true in Webmail → Settings.
• Check the uid_validity column in webmail_folders. If it has changed on the server, the cache is automatically purged and re-synced on next access.
• Try clicking Refresh to trigger an incremental sync.
• For persistent issues, manually clear the cache by truncating the webmail_messages table for the affected folder and resetting last_synced_uid to 0.

Attachments not downloading

• Attachments are fetched directly from the IMAP server on demand: they are not stored locally. Ensure the IMAP connection is active.
• If the attachment index is incorrect, the download will fail. This can happen if the message structure changed on the server.
• Check the max_attachment_size setting: it applies to outgoing attachments, not downloads.

Search returns no results

• When local caching is disabled, search queries the IMAP server directly. Some IMAP servers have limited search capabilities.
• When local caching is enabled, search uses MySQL FULLTEXT. Short search terms (under 3-4 characters, depending on MySQL’s ft_min_word_len) may not return results.
• Ensure messages have been synced to the local cache before searching.

Default account not persisting

The WebmailAccountObserver ensures only one account per user can be set as default. When setting a new default, all other accounts for that user are automatically unset. If no default is explicitly set, the first active account is used as a fallback.