Basic IMAP Client Testing

Basic IMAP client - Testing and verifying

How the extension-free IMAP client is tested, what each test proves, and how to check it yourself - on a test server in Docker, inside the FreeITSM Docker image, and against a real mailbox.

• Why it exists: Basic IMAP without the PHP extension
• How it works: Basic IMAP client - Developer Guide

---

The short version

Test	Needs	Proves	Result (Nov 2026)
php tests/imap-client-parse.php	nothing	Server replies are read correctly - lists, literals, BODYSTRUCTURE, ENVELOPE, encoded names, the injection guard	44 passed
php tests/imap-client-live.php	Docker test servers (below)	FreeITSM's real mailbox functions work against real IMAP servers - Dovecot and GreenMail - end to end	86 passed
Both, inside the FreeITSM Docker image	the image + the test servers	It works where it never could before: Debian 13, PHP 8.4, no imap extension	44 + 86 passed
php tests/docker-php-extensions.php	nothing	No imap_*() call can creep back in	passes; fails when one is added (checked)
php tests/outbound-email-mime.php	nothing	Sending is unchanged after the shared TLS change	32 passed
php tests/mailbox-send-test.php	nothing	The port rules, the ! warnings, the Test button's password rule, and the "never said hello" error	36 passed

Every one of these was also run against a deliberately broken input or the old code, so a pass means something - see Controls.

---

1. The parser test - no server needed

php tests/imap-client-parse.php

Feeds includes/imap_client.php reply text in the shapes real servers send, and checks what comes out. It reads nothing and writes nothing, so it is safe anywhere.

Section	Cases
Values	lists, quoted strings with \" and \\, NIL, a literal containing CRLFs with the list carrying on after it, BODY[HEADER.FIELDS (SUBJECT FROM)] as one atom, a truncated list (no infinite loop), a literal shorter than declared
What we send - the injection guard	a plain value is quoted; " and \ escaped; a password with CRLF + a second command becomes one literal; non-ASCII becomes a literal with its byte length
Folder names	Support/Übergabe ↔ Support/&ANw-bergabe; R&D round-trips
Encoded headers	base64 and Q forms, underscores as spaces, ISO-8859-1, Windows-1252 € and curly quotes, adjacent encoded words, plain text around them, an unknown charset
BODYSTRUCTURE	single part; mixed > alternative > plain + html; an attachment; an inline image with Content-ID; an attached email (message/rfc822, the awkward field positions); a part with no extension data
Filenames	RFC 2231 with charset; continuations filename*0* + filename*1*; RFC 2047 inside quotes; both forms present - filename* wins; fallback to name; none
ENVELOPE	encoded subject and name; a group marker skipped; cc and Message-ID; a missing envelope
Transfer encodings	base64 across lines, quoted-printable soft breaks, 7bit, broken base64

2. The live test - real IMAP servers in Docker

Start the test servers

docker run -d --name freeitsm-imaptest-dovecot -e USER_PASSWORD='{PLAIN}pass' \
    -p 31143:31143 -p 31993:31993 dovecot/dovecot:latest

docker run -d --name freeitsm-imaptest-greenmail \
    -e GREENMAIL_OPTS='-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled' \
    -p 3025:3025 -p 3143:3143 -p 3993:3993 greenmail/standalone:2.1.3

• Dovecot is the server most cPanel and Linux hosts run - the realistic one. Its image accepts any username with the password pass, offers SSL on 31993 and STARTTLS on 31143, and refuses passwords on an unencrypted connection - which tests that path too. It also speaks IMAP4rev2.
• GreenMail is a test mail server that accepts any login and also takes mail by SMTP on 3025 - which allows the send-then-read round trip.
• Both use self-signed certificates, which the test uses to prove certificate checking is on (below).

Run it

php tests/imap-client-live.php

A server that is not running is skipped and named - never counted as a pass. With neither running it exits with code 2. Each run signs in as a new user, so it always starts from an empty mailbox. It needs no database and no FreeITSM install, and does not touch real mail.

What it does, per server

1. Certificates (first, while verification is on) - connecting to the self-signed server must be refused. Then it turns on the install-wide SSL_VERIFY_PEER = false, as an operator with a self-signed server would.

2. Signing in - SSL; STARTTLS (Dovecot); unencrypted - Dovecot's LOGINDISABLED must produce "will not accept a password on an unencrypted connection" without sending the password, GreenMail must sign in; a wrong password; a password containing CRLF and A9999 LOGOUT must fail sign-in as one value, and the connection must still be in step afterwards; a port nobody listens on.

3. Six test emails are put in with APPEND:

   #	Email	Checks
   1	plain text, encoded subject Drucker im Büro, encoded sender Jörg Müller, To and Cc	subject, name, addresses, date in UTC, body escaped and line-broken exactly as before
   2	HTML with a plain alternative	the HTML wins
   3	mixed > related { HTML + inline logo with Content-ID } + PDF named Übersicht Q3.pdf (RFC 2231)	HTML found two levels down; both attachments; the PDF's name and bytes identical; not inline; the logo inline with its Content-ID, bytes identical
   4	Latin-1, quoted-printable Café machine is broken	converted to UTF-8
   5	an attached email (message/rfc822)	it is an attachment, whole, and the outer text is the body
   6	no Message-ID	the mailbox-scoped de-duplication key imap-<mailbox>-<uid>

4. Reading through imapGetEmails() - the function the poll calls - oldest first.

5. Nothing is marked read by reading - all six still unread afterwards; max_emails_per_check = 2 reads the two oldest.

6. After import through imapHandleAfterProcessing() - mark read; move to Übergabe (a non-English folder); delete; move with no folder deletes (as before); a move to a missing folder names it and leaves the message where it was.

7. Verify through imapVerifyFolder() - finds Übergabe with its counts, finds processed whatever the capitals, names a missing folder and lists the real ones, reports a wrong password as a sign-in failure rather than "folder not found".

8. An older server - MOVE and UIDPLUS hidden: the move must use COPY + EXPUNGE, and really move; delete must use plain EXPUNGE.

9. Mail arriving mid-session - a second connection delivers a message; NOOP must return the server's unrequested * n EXISTS and the client read past it; the next search finds the new message.

Then, once, the round trip - FreeITSM's own SMTP sender (imapSmtpSend()) sends a reply with a subject containing – and ✓, a PDF named Bericht für Sie.pdf and an inline image to GreenMail, and FreeITSM's own reader reads it back: subject, sender name, the attachment's real name and bytes, and the image's Content-ID.

The round trip found a real bug the one-sided tests had not: the sender writes both an ASCII fallback name and the real RFC 2231 name, and the reader preferred the fallback - "Bericht f__r Sie.pdf". Each half was right on its own. That is why the round trip is a permanent part of the test, not a one-off.

Remove the servers when done

docker rm -f freeitsm-imaptest-dovecot freeitsm-imaptest-greenmail

3. Inside the FreeITSM Docker image

The point of #257 was the published image, so the tests also run inside it - Debian 13, PHP 8.4, and no imap extension, which the test prints as its first line.

docker build -t freeitsm-imaptest-image:local .

docker run --rm --add-host=host.docker.internal:host-gateway \
    -e FREEITSM_IMAP_TEST_HOST=host.docker.internal \
    -v "$PWD/tests:/var/www/html/tests:ro" \
    --entrypoint sh freeitsm-imaptest-image:local \
    -c 'cd /var/www/html && php tests/imap-client-parse.php && php tests/imap-client-live.php'

• The tests/ folder is not copied into the image, so it is mounted read-only.
• FREEITSM_IMAP_TEST_HOST points the live test at the test servers on the host.
• On Windows with Git Bash, prefix with MSYS_NO_PATHCONV=1 and use the full Windows path in -v, or the paths get mangled.

Result: imap extension loaded: no - and 44 + 86 passed, round trip included.

The Test button and port rules - tests/mailbox-send-test.php

php tests/mailbox-send-test.php

1. Ports - every judged pair, both ways; 25 and 2525 not judged; plain on 587 not flagged.
2. The "!" warnings - the Zoho case (465 + STARTTLS) is flagged as a dismissible warning; fixed, it goes; IMAP 993 + STARTTLS separately; no SMTP server, no port warning; a Microsoft mailbox never judged; a dismissed one stays listed.
3. The password rule - unsaved settings are what get tested; blank or ******** reuses the saved password only for the same server and username; a changed server or username is refused (both for the IMAP login and a separate SMTP login); a typed password with a new server is allowed; Microsoft tested as saved; Google never saved asks to save first.
4. A server that never says hello - a local server accepts and hangs up; the error says never said hello and gives the port advice, not expected 220, got "".

Checked against the real Zoho mailbox, saved as 465 + STARTTLS (stops at the greeting - no sign-in, nothing sent):

smtp.zoho.eu:465 accepted the connection but never said hello (no SMTP greeting).
Port 465 expects SSL, not STARTTLS - set SMTP encryption to SSL (or use port 587 with STARTTLS).

And in the real settings page, in headless Chrome: the button shows for the IMAP mailbox, the click reaches the server, no script errors.

Controls - proving the tests can fail

A test that cannot fail proves nothing. Each of these was checked by making it fail on purpose:

Test	Control	Result
Certificates	connect with verification on to a self-signed server	refused - so verification really is on
Docker extension guard	add a file calling imap_open()	fails, naming the file
Injection	a password containing CRLF and a second command	sign-in fails as one value; the next command still gets a sensible reply
Parser - filenames	the ASCII-fallback-plus-RFC-2231 case against the code before the fix	fails ("f__r")
Older servers	hide MOVE and UIDPLUS	the fallback commands are sent, and the outcome is the same
Test button password rule	a copy of mailboxTestResolve() with the rule removed	the stored password goes to smtp.attacker.example - so section 3 would fail

---

4. Verifying against a real mailbox

The automated tests use test servers. Before a release - or if you want to see it for yourself - connect a real one. Use a test mailbox, not your live helpdesk address, because messages will be turned into tickets and then marked read, moved or deleted by your post-import action.

Gmail (the easiest real-world check):

1. On a Google account with 2-step verification, create an app password (Google Account → Security → App passwords).
2. Tickets → Settings → Mailboxes → Add: Provider Basic IMAP, IMAP imap.gmail.com port 993 SSL, username = the full address, password = the app password; SMTP smtp.gmail.com port 587 STARTTLS.
3. Send it an email with an attachment, then press Check emails.

A cPanel or hosting mailbox: usually mail.yourdomain.com, IMAP 993 SSL, SMTP 465 SSL or 587 STARTTLS, and the folder may be called INBOX.Something - Verify lists the real names.

What to check:

• Test (under Test sending) - the email arrives in your own inbox
• Verify folder shows the folder and its counts
• Check emails creates a ticket; subject, sender and body are right
• an attachment with an accented name arrives with that name and opens
• a pasted (inline) image shows in the ticket
• the post-import action happens (read / moved / deleted) - and nothing is touched before import
• a reply from the ticket arrives, with its attachment
• the setup page no longer mentions imap

Not covered by the automated tests, and so worth a real-mailbox check: Microsoft Exchange's own IMAP quirks (Microsoft 365 uses the Graph connector instead, and Exchange Online no longer accepts passwords over IMAP), very large mailboxes, and mail from unusual clients.

5. When something goes wrong

The errors say which step failed, in the server's own words where there are any:

Message	Means	Do
IMAP connection to host:port failed: ...	nothing answered, wrong host/port, or a firewall	check server and port (993 SSL, 143 STARTTLS)
...the server's certificate could not be verified	self-signed or wrong-name certificate	fix the certificate, or set SSL_VERIFY_PEER to false in config.php for the whole install
does not offer STARTTLS on port 143	encryption set to STARTTLS on a port that only does SSL, or a server without it	choose SSL on 993
will not accept a password on an unencrypted connection	encryption "none", and the server rightly refuses	choose SSL or STARTTLS
IMAP sign-in failed: [AUTHENTICATIONFAILED] ...	wrong username or password	use the full address; many providers need an app password
Folder "X" was not found... Folders on the server: ...	the folder name differs	copy the name exactly as listed, e.g. INBOX.Support
The IMAP server stopped responding (timed out after 30 seconds)	a slow or stuck server	try again; check the server

Related

• Basic IMAP without the PHP extension · Developer Guide
• Basic IMAP / SMTP Mailboxes
• Developer Tests