Mail Gateway imports email into FOSSBilling support tickets using the existing FOSSBilling cron. Configure multiple IMAP mailboxes and route each one to a separate helpdesk.

Features

Create customer tickets from recognised email addresses and guest tickets from unknown senders.
Add replies to existing tickets using the ticket number in the subject.
Check that the sender owns the ticket before accepting a reply.
Filter recognised automatic messages and prevent duplicate imports.
Move handled emails into Processed, Ignored or Failed folders.
Manage mailbox connections and test them from the admin settings page.

Requirements

FOSSBilling with the Support module enabled and its cron running regularly.
An IMAP server supporting native MOVE and a valid TLS certificate when using TLS.
A receiving mail server with appropriate email authentication and anti-spoofing policies.
The webklex/php-imap Composer package and its required PHP extensions.

The native PHP IMAP extension is not required. Composer checks dependency requirements when installing. For installation through the settings page, the web server also needs access to PHP CLI, Composer, proc_open, a writable module directory and package downloads. If web installation is unavailable or the module directory is deliberately not writable by the web server, installation over SSH is the preferred fallback. Run this from the module directory as its owning user:

composer install --no-dev --prefer-dist --no-interaction --no-scripts --no-plugins --optimize-autoloader

This uses the supplied lock file. The web server still needs read access to the installed dependencies; it does not need write access to them for importing.

Installation

Place the module in modules/Mailgateway.
Activate Mail Gateway in FOSSBilling. Activation creates the module tables, registers its sender-mismatch email template and attempts to install dependencies.
Open Mail Gateway's settings from the Extensions page. If dependencies were not installed automatically, use Install dependencies or run composer install in the module directory.
Configure the receiving email address, helpdesk, IMAP connection details and inbox and destination folders, then save.
Select Test Connection and Create Folders. This verifies the connection and creates missing destination folders without processing emails.
After a successful test, enable mailbox importing and save again. This also configures ticket acknowledgement and notification subjects automatically.

Notification template changes persist: enabling importing or running Configure ticket notifications enables the ticket acknowledgement and adds missing ticket references to existing FOSSBilling notification subjects. These changes apply to those templates throughout FOSSBilling. Disabling or uninstalling Mail Gateway does not restore their original subjects or enabled state. If you want to restore them later, keep a copy of the original settings and edit the templates manually in FOSSBilling's Email settings.

Use Add mailbox to configure additional addresses. Each mailbox has its own connection details, folders and helpdesk. All four folder paths must be distinct; the inbox must already exist.

Importing remains disabled until dependencies are installed and the mailbox has passed its connection and folder test. Changing connection details or folder paths requires another successful test. The settings page shows the results and explains any failures.

No additional cron entry is needed. The module polls every five minutes by default, provided the FOSSBilling cron runs that often.

Tickets and replies

Email from a customer's primary email address creates a customer ticket. Unknown senders create guest tickets when guest tickets are enabled in Support. New tickets go to the mailbox's selected helpdesk.

Replies are matched by a subject marker such as [Ticket #123]. The sender must own the referenced ticket. Emails without a ticket marker create a new ticket; reply headers are not used for matching.

Sender matching uses the email's From address; it does not prove that the sender controls that address. Mail Gateway does not independently verify SPF, DKIM or DMARC, and relies on the receiving mail server to apply authentication and anti-spoofing policies before mail reaches the imported inbox. Configure those policies to reject or quarantine suspicious messages outside that inbox. A forged message accepted into the inbox could impersonate a customer or the owner of a guest ticket. Guest reply ownership is based on the original sender's email address, without an authenticated customer account.

Enabling mailbox importing automatically enables the mod_support_ticket_open acknowledgement and adds [Ticket #{{ ticket.id }}] to its subject and enabled staff notification subjects where missing. Existing wording is preserved and disabled optional staff notifications stay disabled. Notifications are delivered through FOSSBilling's email queue.

For an existing mailbox, use Advanced → Configure ticket notifications to run the same setup. Notification status is shown in Advanced, with any problems also displayed at the top of the page. Setup does not send test emails. You can edit notification wording in FOSSBilling's Email settings; keep the ticket marker in subjects so replies can be matched.

The included mailgateway_sender_mismatch template uses your company name and email signature to tell senders when their address does not match the referenced ticket. It is installed only if missing. Its wording can be edited or the notification disabled in Email settings. Existing custom templates are preserved.

Messages use plain text when available, with HTML converted to text otherwise. Quoted reply history is retained. Attachments stay in the archived email and are not attached to tickets.

Email handling

Result	Destination
Imported ticket, reply or duplicate	Processed
Recognised automatic message	Ignored
Invalid message or rejected reply	Failed
Temporary connection or database failure	Inbox, for retry

Only the configured inbox is imported, including already-read messages. Duplicate tracking prevents repeated imports, including when a folder move needs to be retried. To retry a rejected email after resolving its cause, move it from Failed back to the inbox.

Recognised automatic messages receive no response. Unmarked automatic messages cannot always be identified; a notification cooldown limits automated acknowledgements and sender-mismatch notices to one per sender per hour by default.

Configuration and maintenance

Mailbox settings are stored in the database, with passwords encrypted using FOSSBilling's encryption helper. Leaving a password blank keeps the saved value; use the password-clearing option to remove it.

Operational settings are in config.php, including polling limits, timeouts, message size limits, notification cooldown and executable paths. Edit this file over SSH; changes take effect on the next cron run or web request. By default, each run handles up to 50 messages per mailbox, with a shared 90-second time budget. Complete emails are limited to 5 MiB and ticket bodies to 65,535 bytes.

The settings page's Advanced section provides notification setup, Composer installation and table setup. Table setup creates missing tables and the default mismatch template without deleting existing data or replacing customised templates.

Deleting a mailbox removes its configuration while keeping emails, folders, tickets and message tracking.

The following commands are available from the module directory:

# Test a saved mailbox without processing emails.
php tools/test-imap.php

# Test another mailbox and create missing destination folders.
php tools/test-imap.php --mailbox=billing@example.com --create-folders

# Import mail immediately.
php tools/poll.php --force

# Create missing tables and register the default email template.
php tools/setup.php

A connection test with --create-folders records the mailbox's readiness, just as the settings-page test does. A read-only test does not change readiness.

Compatibility note

The module loads its own Composer dependencies into the same PHP process as FOSSBilling. Shared Symfony or Illuminate packages are not isolated by the module's separate vendor directory. Check installation, connection testing and importing on your FOSSBilling version before deploying; compatibility across clean FOSSBilling installations and versions has not yet been established.

During imported ticket creation, the module temporarily wraps FOSSBilling's mod_service factory to intercept email calls. This applies the acknowledgement cooldown and suppresses the separate canned-response email while retaining its ticket history. Other module lookups are delegated to the original factory, which is restored in a finally block, including when creation fails.

Ticket-creation hooks also see this wrapped factory: email services obtained during that scope are proxies, and matching notification codes are intercepted. The installed FOSSBilling notification interfaces provide no per-ticket suppression option. This integration should be reviewed when upgrading FOSSBilling or adding hooks that send emails during ticket creation.

License

MIT. See LICENSE.