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 FreeITSM's own IMAP client (search unread, fetch, flag) - nothing to install
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. [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)
    • Save a copy of sent mail - off by default. Turn it on if people also read this mailbox in Thunderbird or webmail and should see what the service desk sent - but only if your mail server does not already file sent mail itself (see below)
    • The usual shared settings: folder (default INBOX), max emails per check, and the post-import / rejected-email actions
  4. Click Test, under Test sending. FreeITSM sends a short email to you through this mailbox, the same way a reply goes - using what is typed, so you can check before saving. If it fails it says which step and what to change.
  5. Save. There's no sign-in step — click the Check emails (envelope) icon to pull mail immediately, or leave it to the ticket inbox, which checks every minute while somebody has it open. The mailbox shows a Connected badge and reads straight from the target inbox.

Test sending

The Test button sends a short email to you - the address on your analyst account, nobody else - through this mailbox, exactly as a reply would go. It is recorded in the mailbox's send log as Mailbox test.

  • Basic IMAP is tested with what is typed, saved or not, so you can try a setting before committing to it.
  • Leave the password blank to use the saved one - but only while the SMTP server and username are the ones it was saved with. Change either and you need to type the password: the saved one is never sent to a server it was not saved for.
  • Microsoft 365 and Google mailboxes are tested as saved, because they send with their sign-in, and the result says so.
  • When it fails, the message names the step - no greeting, STARTTLS refused, sign-in refused, sender refused - and, when the port and encryption do not belong together, what to change.

Port and encryption go together

Port Encryption
SMTP 465 SSL
SMTP 587 STARTTLS
IMAP 993 SSL
IMAP 143 STARTTLS

A mailbox whose settings break this gets a ! warning on its row - "Sending will fail: the SMTP port and encryption do not match" - before anybody tries to reply. The classic is STARTTLS on 465: the mailbox collects mail perfectly, and every reply fails. It is a warning you can dismiss, because a provider can run something unusual on a port. Other ports (25, 2525, a provider's own) are not judged.

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.

Save a copy of sent mail

A Basic IMAP mailbox sends through SMTP, and SMTP only delivers - it keeps no copy. So if people also open the support mailbox in Thunderbird, Outlook or webmail, its Sent folder stays empty and they cannot see what the service desk replied. (Microsoft 365 and Google mailboxes never had this problem: those services file what FreeITSM sends.)

Turn on Save a copy of sent mail - just below Use the IMAP login for sending in the mailbox settings - and every email the mailbox sends is also put in its Sent folder, marked as read, exactly as it went out, attachments included.

What is filed: replies and forwards, template emails (ticket logged, resolved and so on), workflow emails, portal and system emails such as password resets, the mailbox's own oversized-email alerts and auto-replies, and the Test email. What is not: the internal notifications that go to analysts - those never reach Sent on Microsoft 365 either.

Leave it off if your mail server already files sent mail. Gmail does, Microsoft 365 does when you send through its SMTP, and so do some hosting companies. Turning it on there gives two copies of everything. Not sure? With the switch off, click Test, then look in the mailbox's Sent folder in webmail: if the test email is already there, your server files sent mail and you should leave the switch off.

The Sent folder. When the switch is on, a Sent folder box appears.

  • Leave it blank (the usual choice) and FreeITSM uses the folder your mail server marks as the Sent folder. Most servers mark one; if yours does not, it looks for a folder with a common name - Sent, Sent Items, Sent Messages, Sent Mail, INBOX.Sent.
  • Or type its name, if you want a different folder. Capitals do not matter, and on servers that write folders as INBOX.Sent you can type INBOX/Sent - FreeITSM uses the server's own spelling. The folder must already exist; FreeITSM does not create it.
  • Verify beside the box checks a typed name against the saved mailbox, the same as the other folder boxes. Save the mailbox first.

Checking it works. Click Test. With the switch on, the result adds A copy was saved to "Sent" - naming the folder it used. If the copy could not be saved, the result says why in amber, and the test email itself was still sent. If you changed the IMAP server or username without typing the password, the copy is not tried, and the result asks you to type the password: the saved password is only used with the IMAP server and username it was saved for.

If a copy cannot be saved, the email has still gone. The customer gets their reply either way; only the copy is missing. The reason - for example the server marks no folder as Sent, or the server's own words such as Mailbox doesn't exist - is listed in the mailbox's Activity → Outbound tab as Copy to Sent folder. Choose Failures only to find them. An email that fails to send is never filed as sent.

Good to know:

  • Each copy is a second, short connection to the IMAP server just after the email is sent, so an email with large attachments is uploaded twice - once to send it, once to file it.
  • On an existing installation the two new settings are added by System → Database Verification. Until then the switch does nothing.
  • Suggested in #262 by pappas81; built in #270 for 5.0.0. How it works inside: Basic IMAP - Sent copy - Developer Guide.

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

Nothing to install. From the release after 4.10.0, FreeITSM talks IMAP itself, in plain PHP, so Basic IMAP works the same in the Docker image, on Windows (WAMP/XAMPP), on Debian 13, on shared hosting - anywhere FreeITSM runs.

Upgrading from 4.10.0 or earlier? Earlier versions needed PHP's imap extension, which PHP 8.4 removed and Debian 13 cannot provide - so Basic IMAP did not work in Docker, and on Windows meant downloading a DLL. That is all gone. If you installed the extension for FreeITSM, it is no longer used; you can leave it or remove it. No mailbox settings change.

Why and how:

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…" You are on 4.10.0 or earlier Upgrade - no extension is needed any more
"IMAP connection to host:port failed…" Wrong host or port, or a firewall Verify the IMAP server/port; confirm SSL vs STARTTLS matches the port (993 = SSL, 143 = STARTTLS)
"IMAP sign-in failed: …" Wrong username or password - the server's own reason follows Use the full email address; try an app password
"…certificate could not be verified" The server's certificate is self-signed or for another name Fix the certificate, or turn off verification for the whole install with SSL_VERIFY_PEER in config.php
"…will not accept a password on an unencrypted connection" Encryption is None, and the server rightly refuses Choose SSL or STARTTLS
"…does not offer STARTTLS on port …" STARTTLS chosen on a port that only does SSL Choose SSL on 993
Replies fail: "…accepted the connection but never said hello (no SMTP greeting)" The port and encryption do not match - usually STARTTLS on 465 Do what the message says: 465 = SSL, 587 = STARTTLS. Then Test
Replies fail: "SMTP sign-in failed: …" Wrong username or password for sending Try an app password; if your provider gives a separate sending login, turn off Use the IMAP login for sending
Replies fail: "The SMTP server will not send as …" The provider refuses that From address Make Target mailbox the address the login owns
Replies fail: "SMTP connection … failed" Wrong SMTP host or port, or the provider blocks the submission port Check the SMTP server/port; some hosts require the "authenticated SMTP" / submission service to be enabled
Mail read but never leaves the inbox Imported-email action is Mark as read and leave it in the folder Expected - it is for mailboxes people also read in Thunderbird or Outlook. Set it to delete or move to folder if you'd rather it left the inbox
Replies are sent but never appear in the Sent folder Save a copy of sent mail is off (the default) Turn it on in the mailbox settings - unless your server files sent mail itself; see Save a copy of sent mail
Every sent email appears twice in the Sent folder Your mail server already files sent mail, and Save a copy of sent mail is on too Turn the switch off
Copy to Sent folder failures in Activity → Outbound The folder could not be found or written to - the reason follows Leave Sent folder blank, or type a folder that exists; check the IMAP login still works. The emails themselves were sent
A message in the inbox was never turned into a ticket Somebody read it in their mail program before FreeITSM checked FreeITSM collects unread mail only. Mark it unread and the next check imports it

Related pages