Basic IMAP Mailboxes

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

1. Tickets → Settings → Mailboxes → Add mailbox.
2. Set Provider to Basic IMAP / SMTP. The OAuth fields (client ID/secret, redirect URI, scopes, Authenticate button) disappear — basic IMAP needs none of them.
3. Fill in:
   • Display name and Target mailbox (the address, e.g. support@yourdomain.com)
   • 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)
   • The usual shared settings: folder (default INBOX), max emails per check, and the post-import / rejected-email actions
4. 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.

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:

1. Download the extension from PECL: https://pecl.php.net/package/imap/1.0.3/windows
2. 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.
3. Copy php_imap.dll into your PHP ext\ folder (e.g. C:\wamp64\bin\php\php8.4.0\ext\).
4. 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).
5. 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 is HTML, no outbound attachments. Replies, SLA-breach notifications and template emails send as HTML (the same as the Gmail path). Attaching files to outbound replies isn't supported on the basic-IMAP path.
• 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

---

Related pages

• 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