Implement IMAP email-to-ticket gateway

README.md

@@ -0,0 +1,190 @@
+# Mail Gateway for FOSSBilling
+
+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:
+
+```bash
+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
+
+1. Place the module in `modules/Mailgateway`.
+2. Activate Mail Gateway in FOSSBilling. Activation creates the module tables,
+   registers its sender-mismatch email template and attempts to install dependencies.
+3. 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.
+4. Configure the receiving email address, helpdesk, IMAP connection details and
+   inbox and destination folders, then save.
+5. Select **Test Connection and Create Folders**. This verifies the connection
+   and creates missing destination folders without processing emails.
+6. 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:
+
+```bash
+# 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
+
+Apache-2.0.