Basic IMAP Mailboxes

Basic IMAP / SMTP Mailboxes

Connecting a plain mailbox — a hosting/cPanel inbox, Fastmail, a generic mail.example.com account with a username and password — instead of Microsoft 365 or Google Workspace.

Note

Status: planned (roadmap). As of this writing FreeITSM connects mailboxes only via Microsoft 365 (Microsoft Graph API) or Google Workspace (Gmail API), both of which require an OAuth app registration. Basic IMAP/SMTP is not built yet. This page captures the design so it can be built and then turned into a setup guide. See Mailbox Authentication for what exists today.

---

Why add it

Both current providers assume an enterprise identity platform — an Azure/Entra app registration or a Google Cloud OAuth client. That's the right choice for Microsoft 365 and Workspace tenants, but it's overkill (or simply unavailable) for a smaller operation whose 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 + SMTP with a username and password

For these, there's no OAuth to configure — you just want to hand FreeITSM a host, a login, and a password.

How it will work (design)

The mailbox pipeline is already provider-branched end to end ($mailbox['provider'] is microsoft or google today). Adding imap as a third provider follows the exact pattern the Gmail connector established: a self-contained helper whose functions normalise every message to the same internal shape, so nothing downstream (ticket creation, attachments, whitelist, multi-tenancy routing) needs to change.

Concern	Microsoft / Google (today)	Basic IMAP (planned)
Auth	OAuth 2.0 — app registration, client ID/secret, sign-in or client-credentials	Username + password, per connection. No app registration, no sign-in dance
Reading mail	Graph API / Gmail API over HTTPS	PHP imap_* functions (imap_open, search UNSEEN, fetch, flag)
Sending replies	Graph / Gmail send endpoints	SMTP with auth (STARTTLS/SSL)
Credentials stored	Client secret + OAuth tokens (encrypted)	IMAP/SMTP 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

The one genuinely new piece: sending

Reading over IMAP is straightforward. Sending is not — IMAP is receive-only, so replies go out over SMTP, and correct SMTP (auth, STARTTLS, MIME multipart, attachments) is the part worth getting right rather than hand-rolling. The intended approach is a small, self-contained SMTP sender (e.g. PHPMailer) invoked from the same provider branch the Gmail send path already uses.

Server dependency

Basic IMAP requires PHP's imap extension to be enabled — neither current provider needs it (both are pure HTTPS/cURL). On WAMP/most hosts this is a one-line php.ini toggle, but self-hosters should expect to enable it.

What you'll enter (planned UI)

Under Tickets → Settings → Mailboxes, choosing Provider = Basic IMAP will show a simpler form than the OAuth providers — no redirect URI, scopes, or Authenticate button:

• IMAP: server, port (usually 993), encryption (ssl)
• Login: username + password
• SMTP (for replies): server, port (usually 587), encryption (tls)
• The usual shared settings: display name, target address, folder, max emails per check, post-import action

Trade-offs to be aware of

• Passwords, not tokens. A stored mailbox password is a long-lived credential. FreeITSM encrypts it at rest (as it does client secrets), but unlike OAuth there's no scoped, revocable token — if the provider offers an app-specific password, prefer that.
• 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, full stop.
• Provider quirks. IMAP folder naming and SMTP submission ports vary between hosts; expect a little per-provider tuning.

---

Related pages

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