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
• WAMP/XAMPP → uncomment extension=imap in php.ini and restart

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