Webmail Client Add-on Guide for Larapen

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: Upload the Add-on

In the admin panel, go to Admin → Extensions → Add-ons and click the Upload Add-on button. Select the add-on’s ZIP file: the system extracts it automatically and the add-on appears in the installed add-ons list.

Step 2: Activate the Add-on

Find Webmail Client in the list and click Activate. Its migrations, seeders (if any) and permissions are set up automatically.

Step 3: Configure

Navigate to Admin → Webmail → Settings to configure global options (cache, messages per page, auto-refresh). See Configuration.

Step 4: Add an Email Account

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

Purchase Code (License Key)

Webmail Client is sold as a separate product, so it has its own purchase code (license key), distinct from the purchase code of the main application and from the one of every other add-on. You are asked for it when you activate Webmail Client in Admin panel → Add-ons.

Our products are sold on three platforms. The way you receive a purchase code depends on where you bought the product.

1. bedigit.com Store (in-site purchase)

• As soon as the order’s payment status becomes Paid, a license key is generated automatically for every licensed item in the order (one key per purchased unit: buying 3 units gives 3 distinct keys).
• It is emailed to the address used on the order, either in a dedicated license email or inside the order confirmation email. Check your inbox and your spam / junk folder.
• The key stays available in your account under My Account → My Licenses. Keys are masked in the list; open the license detail page to reveal and copy the full key, see the domains it is activated on, and deactivate a domain to free an activation slot.
• The matching invoice is under My Account → My Orders.

2. Gumroad

• A Gumroad purchase produces two separate emails: the Gumroad receipt (sent by Gumroad, giving access to the files) and a license key email (sent by bedigit.com) that contains your purchase code.
• The license key email is generated as soon as Gumroad notifies us of the sale, so it normally arrives within seconds of the payment. Here too, check your inbox and your spam / junk folder.
• When the Gumroad product uses Gumroad’s own license-key feature, the same key also appears in your Gumroad receipt and under Library → your purchase on gumroad.com.
• Use the same email address on bedigit.com as on Gumroad: your keys are then linked to your account automatically and listed under My Account → My Licenses, even if you register after the purchase. You can also add a Gumroad key manually from My Account → My Gumroad Licenses.

3. Envato Market (CodeCanyon)

• Envato purchase codes are issued and delivered by Envato Market, never emailed by us, so there is nothing to look for in your spam folder: you retrieve the code from your Envato account.
• Log in to your Envato / CodeCanyon account, open the Downloads page, find the item, and choose License certificate & purchase code from the Download dropdown. The code is written in that certificate.
• An Envato purchase code looks like 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 characters). It never changes, and renewing item support does not issue a new one.
• Official Envato article: Where Is My Purchase Code?

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).

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:

Common IMAP & SMTP Settings

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):

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

There are two ways to update this add-on: via the admin panel (recommended) or manually replacing files.

Method 1: Admin Panel Upload (Recommended)

1. Download the latest .zip file of this add-on.
2. Go to Admin panel → Add-ons and click the Upload button.
3. Select or drag the .zip file into the upload area.
4. A confirmation prompt will show the current and new version numbers. Click Replace to proceed.
5. Go to Admin panel → System Update (/admin/update) to apply any pending database migrations.

Method 2: Manual File Replacement

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

php artisan migrate

Pending migrations run once, so the command is safe to repeat.

Step 3: Clear Caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

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.

Uninstallation

Switching an add-on off without losing anything is a deactivation: go to Admin panel → Add-ons, find Webmail Client and click Deactivate.

• Its routes, views, admin menu entries and permissions stop being registered, and its front-end pages stop answering.
• Its database tables and all the data they hold are kept, and its files stay under extensions/addons/webmail/. Nothing is deleted.
• The purchase code recorded at activation is kept too, so activating the add-on again does not ask for it.
• Deactivation is refused while another active add-on depends on this one: deactivate that add-on first.

Click Activate on the same card to switch it back on. Pending migrations are re-run, assets are republished, and the add-on picks up exactly where it left off.

Removing

Removing is permanent and destroys the add-on's data. The Remove button only appears on a deactivated add-on, so removal is always two steps:

1. Deactivate Webmail Client (see Uninstallation).
2. Click Remove on its card and confirm the prompt.

The admin panel then, in one pass:

• runs the add-on's uninstall hook, if it ships one, while its code is still on disk;
• revokes the permissions declared in its addon.json;
• rolls back its migrations (this drops its database tables and every row they hold) and purges its entries from the migrations table, so a later reinstall migrates from scratch;
• deletes its published assets: public/addons/webmail/, public/vendor/webmail/ and storage/app/public/addons/webmail/;
• deletes the add-on directory extensions/addons/webmail/;
• deletes its row in the addons table (the recorded purchase code goes with it) and clears the application cache.

Removal is refused, with an explanatory message and before anything is destroyed, when the add-on is still active, when another active add-on depends on it, or when the web server (PHP) user cannot delete extensions/addons/webmail/. In that last case, give that user write permission on the directory and on its parent, then try again.

Deleting the folder over FTP or SSH is not equivalent: the add-on's tables, its entries in the migrations table and its addons row are all left behind, and its card stays in the list. Use Remove in the admin panel instead.

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.