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

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

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.

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).

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.

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.

Save a copy of sent mail (#270) - per server, over SSL: the Sent folder is found with the setting blank (Dovecot marks it \Sent; GreenMail does not, so it is found by name - the run prints which), imapSaveSentCopy() stores a message that is read back byte for byte and marked read, a folder typed as sent goes to Sent, and a missing folder gives an error naming it, never an exception. Then a second round trip on GreenMail: a reply with a PDF is sent with the switch on and is found in Sent with its attachment, and an internal notification is not. Details: Sent copy - Developer Guide.

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

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.

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.

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

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.

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

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