MTS Email Client — Admin Guide

Version: 1.1.0 Compatible with: SuiteCRM Community Edition Last Updated: 2026-07-05

---

Table of Contents

1. Overview
2. System Requirements
3. Installation
4. License Activation
5. Email Account Setup
6. Admin Settings
7. Background Sync & Index
8. Uninstallation
9. Troubleshooting

---

Overview

MTS Email Client is a SuiteCRM module that replaces the default email interface with a modern, Gmail-style inbox. It provides a 3-panel layout (folder sidebar, email list, email reader), a floating compose modal, and deep CRM integration including record linking and quick-create.

The module ships in two license plans: - One-Time — single purchase, permanent use - Yearly — annual subscription

---

System Requirements

Requirement	Minimum
SuiteCRM	7.12 or higher
PHP	7.4 – 8.3
PHP extensions	curl, imap, zip, openssl
IMAP server	Any standard IMAP server (Gmail, Outlook, etc.)
Browser	Chrome 90+, Firefox 88+, Edge 90+, Safari 14+

Note: PHP curl is required for license validation. The admin license page will display a warning if curl is not enabled.

PHP imap extension: For basic-authentication accounts the module uses the native imap extension when it is available (it is the most compatible and correctly handles CRAM-MD5 / DIGEST-MD5). Make sure imap is enabled: php -m | grep imap. If the extension is not present, the module automatically falls back to SuiteCRM's built-in pure-PHP IMAP client. OAuth (Gmail / Microsoft 365) accounts always use the built-in client.

---

Installation

Step 1 — Upload the Package

1. Log in to SuiteCRM as Administrator.
2. Navigate to Admin → Module Loader.
3. Click Choose File and select the ZIP file:
   • One-Time plan: MTS_Email_Client_1.1.0.zip
   • Yearly plan: MTS_Email_Client_Yearly_1.1.0.zip
4. Click Upload.
5. After the upload completes, click Install next to the uploaded package.
6. Review the pre-install check and click Commit.

Step 2 — Repair (required)

After installation, always run a Quick Repair and Rebuild. This is required in 1.1.0 so the background inbox sync scheduler is registered and the inbox index tables are created:

1. Navigate to Admin → Repair → Quick Repair and Rebuild.
2. Scroll down and click Execute (run any suggested database changes).

The scheduler "MTS Email Client — Sync Inbox Index" is created automatically and set Active on install. Verify it under Admin → Scheduler. It requires SuiteCRM's cron to be running (see your hosting's cron setup).

Step 3 — Verify

Navigate to index.php?module=Emails&action=inbox to confirm the modern inbox loads correctly.

---

License Activation

The module requires an active license to function. Without a valid license, the inbox will be blocked for all users.

Activating Your License

1. Navigate to Admin → MTS Email Client → MTS Email Client License. Direct URL: index.php?module=MTS_EmailClient&action=license
2. Enter your License Key in the input field.
   • Your license key is available in your SuiteCRM Store account under My Purchases.
3. Click Validate.
4. A success indicator will appear once the key is verified.

License Validation Behavior

• Validation is performed against the SuiteCRM Store API.
• The validation result is cached locally and re-checked once per week.
• If the server cannot reach the API (e.g., no outbound internet), the last cached result is used.
• An admin-level error message with a link to the license page is shown if the license is invalid.
• Regular users see a generic "Contact your administrator" message.

License Plans

Plan	ZIP File	Notes
One-Time	MTS_Email_Client_1.1.0.zip	Permanent, no renewal needed
Yearly	MTS_Email_Client_Yearly_1.1.0.zip	Requires annual renewal

Each plan uses a different public key. Installing the wrong ZIP for your purchased plan will cause validation failure.

---

Email Account Setup

MTS Email Client works with SuiteCRM's built-in InboundEmail and OutboundEmail account records. No separate account configuration is required.

Setting Up an Inbound Email Account

1. Navigate to Admin → Email Settings → Inbound Email.
2. Click Add and fill in your IMAP server details:
   • Server address (e.g., imap.gmail.com)
   • Port (993 for SSL, 143 for STARTTLS)
   • Protocol: IMAP
   • SSL/TLS: Recommended
   • Username / Password
3. Save and test the connection.
4. The account will appear in the MTS Email Client inbox account selector automatically.

Setting Up an Outbound Email Account

1. Navigate to Admin → Email Settings → Outbound Email.
2. Configure the SMTP server for sending emails.
3. Users can also set up personal outbound accounts in User Profile → Email Settings.

Gmail / Google Workspace Notes

• Enable IMAP access in Gmail settings.
• If using 2-Factor Authentication, generate an App Password and use it instead of your Google account password.
• Google may require Less Secure App Access to be enabled for older configurations.

Microsoft 365 / Outlook Notes

• Use OAuth2 or App Password authentication as required by your tenant policy.
• Server: outlook.office365.com, Port: 993 (IMAP), 587 (SMTP)

---

Admin Settings

Navigate to Admin → MTS Email Client → MTS Email Client Settings, or directly at: index.php?module=MTS_EmailClient&action=admin

Level 1 — Compose Override (Global Toggle)

Controls whether the MTS floating compose modal replaces SuiteCRM's default "Compose Email" popup across CRM pages.

Setting	Values	Default
Enable compose override on CRM pages	On / Off	On

• When On: clicking "Compose Email" on any whitelisted CRM module page opens the MTS floating modal.
• When Off: SuiteCRM's default compose popup is used everywhere.

The compose modal is always enabled on the Home dashboard regardless of this setting.

Level 2 — Module Whitelist

Defines which CRM modules display the MTS compose modal. This setting is only effective when Level 1 is On.

Default enabled modules:

Module	Module Key
Accounts	Accounts
Contacts	Contacts
Leads	Leads
Opportunities	Opportunities
Cases	Cases
Bugs	Bugs
Targets (Prospects)	Prospects
Target Lists	ProspectLists
Users	Users
Quotes	AOS_Quotes
Invoices	AOS_Invoices
Contracts	AOS_Contracts
PDF Templates	AOS_PDF_Templates
Events (FP)	FP_events
Event Locations	FP_Event_Locations

To modify the whitelist: 1. Check or uncheck the modules in the grid. 2. Use Select all / Deselect all links for bulk actions. 3. Click Save.

Performance

IMAP connection timeouts and a short cache for the email list. Defaults are fine for most sites.

Setting	Default	Purpose
IMAP connect timeout (seconds)	15	How long to wait when opening a connection before giving up
IMAP read timeout (seconds)	30	How long to wait for the server to respond
Email list cache (seconds)	60	Short cache for a list page; 0 disables

Index & Sync

Controls the local header index that makes browsing instant, and the background sync. See Background Sync & Index for how it works.

Setting	Default	Purpose
Background sync scope	Personal only	Personal only or Personal + group mailboxes — which accounts the background job keeps indexed
Index backfill chunk	500	How many messages are indexed per sync/backfill step
Index freshness threshold (seconds)	180	How old an index may be before the inbox does a silent background refresh; 0 disables
Message body cache (seconds)	3600	How long a read message is served from cache on reopen; 0 disables
Connection cool-down (seconds)	120	How long to skip an account after a failed connection (avoids hammering an unreachable server)

Group (shared) mailboxes are excluded from background sync by default: they are usually high-volume and are already polled by SuiteCRM's core scheduler. They still work in the inbox (synced on open / refresh). Choose Personal + group mailboxes only if your team browses shared mailboxes through this inbox and wants them kept fresh in the background.

---

Background Sync & Index

Version 1.1.0 keeps a lightweight local index of message headers (from, subject, date, read/starred state) per account and mailbox, so the inbox list is served from the database instantly instead of connecting to IMAP on every action. Message bodies are never stored — they are fetched from the server when a message is opened.

How it works

• On first open of a mailbox, the inbox builds the index from the server (a few seconds), then serves everything from it.
• The scheduler "MTS Email Client — Sync Inbox Index" runs every 10 minutes, fetching new mail, reconciling read/deleted state, and progressively backfilling older messages until the whole mailbox is mirrored.
• Completeness: while a large mailbox is still being backfilled, deep pages, tab views and searches for older mail fall back to live IMAP, so nothing is ever missed.
• Freshness without cron: if a list is served from a stale index, the browser does a silent background refresh — so new mail appears even if the scheduler is off.
• Never regresses: if the index is unavailable for any reason, the inbox falls back to live IMAP.

Managing the scheduler

• Admin → Scheduler → "MTS Email Client — Sync Inbox Index" — set Active/Inactive, change the interval, or run it on demand.
• Requires SuiteCRM cron to be running.
• Disabling it does not break the inbox; mail then refreshes on open / via the Refresh button instead of in the background.

Tables created

Table	Purpose
mts_email_index	Per-message header index
mts_email_sync_state	Per-mailbox sync progress
inbound_email.mts_imap_folders_cache	Cached IMAP folder tree (column)

These are created automatically (on install/Repair, or on first use).

---

Uninstallation

1. Navigate to Admin → Module Loader → Installed Packages.
2. Find MTS Email Client and click Uninstall.
3. When prompted about database tables, choose:
   • Remove tables — deletes all module data permanently.
   • Keep tables — retains data for potential reinstallation.
4. Click Commit.
5. Run Quick Repair and Rebuild after uninstallation.

---

Troubleshooting

Inbox shows "License is no longer active"

• The license key is missing, expired, or invalid.
• Go to Admin → MTS Email Client License and re-enter your key.
• Ensure the server can reach https://store.suitecrm.com (outbound HTTPS on port 443).

No email accounts appear in the inbox

• Verify that at least one InboundEmail account is configured and its connection test passes.
• Check that the IMAP account is not marked as a Bounce Handling account (those are excluded from user display).

Folders do not load / IMAP error

• Confirm the IMAP credentials are correct and the connection test in Inbound Email settings passes.
• Check PHP imap extension is installed: php -m | grep imap.
• Some servers (e.g., Gmail) require enabling IMAP in their settings panel.
• Check the log for a specific reason — the module logs the real IMAP error with a [MTS_EmailClient] prefix in suitecrm.log (e.g. grep '[MTS_EmailClient]' suitecrm.log).
• "Mail server temporarily unreachable" means a recent connection failed and the account is in a short cool-down (default 120s). Wait a moment and click Refresh, or fix the account's credentials/host if it persists.
• Wrong host is a common cause: an IMAP account's server must be the IMAP host (e.g. imap.gmail.com), not the SMTP host (smtp.gmail.com).

The inbox is slow the first time I open a mailbox

• This is expected: the first open builds the local index from the server. Subsequent opens are instant. Letting the sync scheduler run keeps mailboxes pre-indexed.

New mail is not appearing automatically

• Confirm the scheduler "MTS Email Client — Sync Inbox Index" is Active and that SuiteCRM cron is running.
• You can always pull new mail immediately with the Refresh button in the inbox.
• The silent auto-refresh triggers when the index is older than the Index freshness threshold (Admin Settings, default 180s).

A group (shared) mailbox is not staying up to date in the background

• By design: group mailboxes are excluded from background sync by default. Set Admin Settings → Index & Sync → Background sync scope to Personal + group mailboxes.

Compose modal does not appear on CRM pages

• Confirm Level 1 (Compose Override) is On in Admin Settings.
• Confirm the module is in the Level 2 whitelist.
• Run Quick Repair and Rebuild to regenerate extension cache.

Emails sent but not appearing in Sent folder

• Sent emails are stored in SuiteCRM's Email module.
• The "Sent (CRM)" folder shows emails sent via SuiteCRM.
• IMAP "Sent" folder shows emails stored on the mail server (only if the outbound account saves copies to IMAP).

Post-install script errors

• Ensure the post_install.php script executed correctly by checking the SuiteCRM logs at suitecrm.log.
• Re-run repair scripts: Admin → Repair → Quick Repair and Rebuild.

---

For further support, contact your MTS vendor or visit the SuiteCRM community forums.