Basic IMAP Mailboxes - edmozley/freeitsm GitHub Wiki

Basic IMAP / SMTP Mailboxes

Connect the ticketing inbox to a plain mailbox — a hosting/cPanel inbox, Fastmail, Zoho, mxroute, Migadu, or any server that speaks IMAP + SMTP — using just a username and password, with no OAuth app registration.

Configure this under Tickets → Settings → Mailboxes → Provider: Basic IMAP. For the Microsoft 365 / Google Workspace connection modes, see Mailbox Authentication.

Why use it

Microsoft 365 and Google Workspace both authenticate through an enterprise identity platform — an Azure/Entra app registration or a Google Cloud OAuth client. That's the right choice for those tenants, but it's overkill (or simply unavailable) when your support address lives on:

a web-hosting mailbox (cPanel/Plesk, mail.yourdomain.com)
an independent provider (Fastmail, Zoho, mxroute, Migadu, …)
any server that speaks IMAP for reading and SMTP for sending

For these there's no OAuth to configure — you hand FreeITSM a host, a login and a password, and it reads mail into tickets and sends replies like any other mailbox.

How it works

Once connected, a basic IMAP mailbox behaves like every other one — inbound email becomes tickets, replies thread back, whitelisting and (on multi-company installs) sender-domain routing all apply. Under the hood:

Concern	Microsoft / Google	Basic IMAP
Auth	OAuth 2.0 — app registration, client ID/secret, sign-in or client-credentials	Username + password, per connection. No app registration, no sign-in
Reading mail	Graph API / Gmail API over HTTPS	PHP *`imap_`** functions (search UNSEEN, fetch, flag)
Sending replies	Graph / Gmail send endpoints	SMTP with auth (SSL or STARTTLS)
Credentials stored	Client secret + OAuth tokens (encrypted)	Password (encrypted at rest, same as the client secret)
"Right inbox" safeguards	Alias/identity checks (Graph `/me`) — see auth page	Not applicable — the login is the mailbox

Inbound mail is fetched with a peek (messages aren't marked read until your configured post-import action runs), MIME bodies and attachments are decoded, and everything is normalised to the same internal shape the Microsoft/Google connectors produce — so nothing downstream needs to know which provider a ticket came from.

Setting one up

Tickets → Settings → Mailboxes → Add mailbox.
Set Provider to Basic IMAP / SMTP. The OAuth fields (client ID/secret, redirect URI, scopes, Authenticate button) disappear — basic IMAP needs none of them.
Fill in:
- Display name and Target mailbox (the address, e.g. [email protected])
- IMAP server / port / encryption — e.g. imap.yourhost.com, 993, SSL/TLS (STARTTLS on 143 and plaintext are also supported)
- Username and Password — usually the full email address and its mailbox password
- SMTP server / port / encryption — e.g. smtp.yourhost.com, 587, STARTTLS (implicit SSL on 465 also supported)
- Use the IMAP login for sending — on by default. Turn it off if your provider issues a different username and password for SMTP, and a second pair of fields appears (see below)
- The usual shared settings: folder (default INBOX), max emails per check, and the post-import / rejected-email actions
Save. There's no sign-in step — click the Check emails (envelope) icon to pull mail immediately, or let the scheduled poll do it. The mailbox shows a Connected badge and reads straight from the target inbox.

Separate SMTP credentials

Most hosts use one account for both reading and sending, which is why Use the IMAP login for sending is on by default and there is nothing extra to fill in. Some do not: a provider may issue a distinct SMTP username, or the mailbox may sit behind a submission relay with its own login. Turn the switch off and a SMTP username and SMTP password appear.

Both are encrypted at rest, exactly as the IMAP password is.
The password behaves like every other secret in FreeITSM: it is never sent back to the browser, and leaving the box blank when you re-open the mailbox keeps the stored one. The placeholder tells you when one is saved.
Turning the switch back on clears both, so sending returns to the IMAP login rather than leaving credentials behind that nothing reads.
On an existing installation the two columns are added by System → Database Verification.

⚠️ This is not a way to send without authenticating. With the switch on, FreeITSM sends using the IMAP username and password, and a basic mailbox always has those. A relay that wants no authentication at all is not configurable here.

Added in #1411, from a contribution by Kraleemil.

App passwords. If your provider offers an app-specific password (many do for IMAP/SMTP access), prefer it over your main account password — it's scoped to mail and easy to revoke.

Server requirement

Basic IMAP needs PHP's imap extension enabled — neither current provider requires it (both are pure HTTPS/cURL). On most hosts this is a one-line change:

cPanel / WHM → MultiPHP INI Editor → enable imap
Debian/Ubuntu → sudo apt install php-imap && sudo phpenmod imap, then restart PHP-FPM/Apache — but see the PHP 8.4 note below if you are on Debian 13 or later
WAMP/XAMPP → uncomment extension=imap in php.ini and restart

PHP 8.4+ — every platform, not just Windows

The imap extension was removed from PHP core in PHP 8.4.0 (it wrapped an abandoned C library) and moved to PECL. That is a change to PHP itself, so it affects every operating system — it is not a Windows quirk. Where you feel it depends on when your distribution moved to 8.4:

Platform	PHP	Status
Debian 12 (bookworm)	8.2	✅ `apt install php-imap`
Debian 13 (trixie) and later	8.4	🔴 No `php-imap` package — not in trixie, not in trixie-backports. Only an `experimental` PECL rebuild
Ubuntu 24.04 LTS (noble)	8.3	✅ `apt install php-imap`
Ubuntu 25.10 (questing) and later	8.4	✅ `apt install php8.4-imap` (universe — Ubuntu packages the PECL build)
Windows / WAMP / XAMPP on 8.4	8.4	⚠️ Manual DLL, see below
Any platform, any PHP	—	`sudo pecl install imap` then add `extension=imap`

🔴 Debian 13 is the one that has no clean answer. sudo apt install php-imap — the command in the list above — simply fails there; the package does not exist. Build it with pecl install imap (you will need libc-client-dev and libkrb5-dev), pull the experimental package, or use one of the two OAuth providers instead, neither of which needs the extension at all.

Windows (WAMP / XAMPP) on PHP 8.4

There's no php_imap.dll in your PHP ext\ folder and nothing to uncomment. You have to add it manually:

Download the extension from PECL: https://pecl.php.net/package/imap/1.0.3/windows
Pick the build that matches your PHP exactly. Check yours with php -i | findstr /C:"Thread Safety" /C:"Architecture" /C:"Zend Extension Build". WAMP and XAMPP run Apache, which on Windows is always the Thread Safe (TS) build — so choose the TS, x64, VS17 DLL (e.g. php_imap-1.0.3-8.4-ts-vs17-x64). The Non-Thread-Safe (NTS) build will not load under Apache.
Copy php_imap.dll into your PHP ext\ folder (e.g. C:\wamp64\bin\php\php8.4.0\ext\).
Add extension=imap to the Apache php.ini. On WAMP that's phpForApache.ini in the PHP version folder (the bin\php.ini under Apache is a symlink to it).
Restart Apache (WAMP tray → Restart All Services).

⚠️ Know what you're accepting on Windows. php.net states plainly: "The IMAP extension is not thread-safe; it should not be used with ZTS builds." Apache on Windows is a ZTS (thread-safe) build, so the TS DLL above is the only one that will load — and it's the one php.net advises against. In practice it works, and it's what everyone running IMAP on WAMP does, but it is a known-unsupported combination rather than a supported one. For a production Windows install, prefer one of the two OAuth providers (neither needs the extension) or run PHP-FPM/NTS behind IIS or nginx.

If the extension is missing, the mailbox reports a clear error on the first check rather than failing silently.

Things to be aware of

Passwords, not tokens. A stored mailbox password is a long-lived credential. FreeITSM encrypts it at rest (as it does OAuth client secrets) and never sends it back to the browser, but unlike OAuth there's no scoped, revocable token — use an app-specific password where you can.
No alias/identity safeguards. The Microsoft delegated-mode protections against "reading the wrong inbox" don't apply here: the login you give is the mailbox.
Sending carries attachments and pictures. Since 2.9.1, a reply or forward sends the files the analyst attached, any screenshot pasted into the body, and the pictures in the quoted thread (up to 2 MB of those per email) — the same as a Microsoft mailbox. Before 2.9.1 the basic-IMAP and Gmail paths sent the HTML alone; see Reply attachments never reached the customer.
Provider quirks. IMAP folder naming and SMTP submission ports vary between hosts; expect a little per-provider tuning (e.g. the folder name for "move imported mail here").

Troubleshooting

Symptom	Cause	Fix
"The PHP IMAP extension is not enabled…"	`imap` extension missing	Enable it (see Server requirement above) and re-check
"IMAP connection failed…"	Wrong host/port/encryption, or bad credentials	Verify the IMAP server/port, try an app password, confirm SSL vs STARTTLS matches the port (993 = SSL, 143 = STARTTLS)
Replies fail: "SMTP connection … failed" / "SMTP error"	Wrong SMTP host/port/encryption, or the provider blocks the submission port	Check the SMTP server/port (587 = STARTTLS, 465 = SSL); some hosts require the "authenticated SMTP" / submission service to be enabled
Mail read but never leaves the inbox	Post-import action is mark read	Expected — set the imported-email action to delete or move-to-folder if you'd rather it left the inbox

Mailbox Authentication — the Microsoft 365 & Google Workspace OAuth connection modes
Tickets — the module these mailboxes feed
Security — how mailbox credentials are encrypted at rest
Multi-Tenancy: Email routing & mailboxes — pinned vs shared-intake mailboxes, sender-domain routing