● Reference · When something is wrong
Troubleshooting
symptoms, causes, checks.
Start with Test connection on the mailbox: it checks IMAP and SMTP separately and shows the mail server's own words next to Mail Desk's explanation. Passwords never appear in error messages or logs.
01Where to look
- Test connection on the mailbox (Connect a mailbox).
- The mailbox's last error, saved at every sync: Sync failed under the mailbox in the Inbox's left column (point at it to read the text), the red banner on its card in Mail Desk > Mailboxes, and the Dashboard's mailbox list.
- When the cron last ran: "Last cron run time ago" in the Sync card of Mail Desk > Settings and on the Dashboard's mailbox card.
- Logs: Mail Desk writes problems with the prefix
[mail_desk]to Perfex's log folderapplication/logs/(when logging is on in Perfex) and to the PHP error log.
02Connection test messages
The test shows one line for IMAP and one for SMTP. Each line is one of the messages below; where the mail server or the connection gave details, they follow in brackets.
| The test says | Likely cause | What to do |
|---|---|---|
| The server name could not be found. Check the server address. | Typing mistake in the host name, or the host does not exist | Copy the host name from your provider's settings page. |
| The server refused the connection. … | Nothing listens on that port, or a firewall refuses it | Check the port; ask your host whether outgoing connections to that port are allowed. |
| The server did not answer in time. A firewall may block this port. | A firewall silently drops the connection (often your host blocking outgoing mail ports), or the server is down | See Ports blocked by the host. |
| The secure connection failed. … | Certificate does not match the host name, is expired or self-signed, or the server is too old for TLS 1.2 | See Certificate errors. |
| This port expects STARTTLS or no encryption, not SSL/TLS. … | Encryption SSL/TLS with port 143, 587 or 25 | Use STARTTLS on those ports, or SSL/TLS with 993 (IMAP) or 465 (SMTP). |
| This port expects SSL/TLS. … | Port 993 or 465 with STARTTLS or None | Use SSL/TLS on 993 and 465. |
| The server closed the connection. Check the port and the encryption setting. | Wrong port or encryption, or the server dropped the session | Check both against your provider's settings. |
| The user name or password was not accepted. For Gmail create an app password … | Wrong password, wrong user name, or the provider needs an app password | See Login failed. |
| This server accepts only OAuth sign-in (Microsoft 365 / Outlook.com), which version 1.0 does not support. | A Microsoft 365, Outlook.com, Hotmail or Live mailbox | Not supported in 1.0 (Microsoft). |
| The server answered with an error. (The server does not offer STARTTLS on this port. …) | STARTTLS chosen, but the port expects SSL/TLS or has no encryption | Switch to SSL/TLS with 993 or 465. |
| The server answered with an error. (The connection is not encrypted, so the password was not sent. …) | SMTP encryption set to None for a server other than localhost | Use SSL/TLS or STARTTLS. |
| The server answered with an error. (The server offers no password login this client supports (PLAIN or LOGIN). It offers: …) | The SMTP server offers only other sign-in methods | Ask your provider for SMTP with AUTH PLAIN or AUTH LOGIN. |
| The server answered with an error. (…) | The mail server refused something and gave a reason | Read the text in brackets; it usually names the problem. |
| Fill in the server, port and encryption for IMAP and SMTP first. | A field in card 3 or 4 is empty or invalid | Complete both server cards. |
03Login failed: wrong password or app password needed
- Gmail and Google Workspace refuse your normal Google password from other programs. Create an app password (needs 2-Step Verification) and use it in the password field (Gmail). Enter its 16 characters without the spaces Google shows between the groups.
- If the App passwords page is missing in a Workspace account, the organisation does not allow app passwords, or 2-Step Verification is not set up; ask your Workspace administrator. Also check that IMAP is allowed for the user in the Admin console.
- After you change your Google password, Google removes existing app passwords; create a new one and enter it on the mailbox.
- Hosting mail: the user name is almost always the full address (
info@yourdomain.com), not onlyinfo. - If IMAP works and SMTP does not, the SMTP user name or password may differ; enter them in the SMTP fields.
- "The saved password cannot be read" means the encryption key changed (for example after moving Perfex without
uploads/mail_desk/). Enter the password again on the mailbox.
04Certificate errors
- Use the host name the certificate is for. On shared hosting that is often the server's own name (shown in cPanel > Email Accounts > Connect Devices), not
mail.yourdomain.com. - Check the certificate is valid. An expired certificate fails too; your host can renew it (many hosts issue free certificates for mail host names).
- Your own server with a self-signed certificate: tick "allow a self-signed certificate" on that mailbox only. This switches off the certificate and host name checks for it.
05Ports blocked by the host
Many shared hosts block outgoing connections to mail ports on other servers, most often SMTP (25, 465, 587). Typical sign: IMAP works, SMTP times out.
- Try the other SMTP port: 465 with SSL/TLS, or 587 with STARTTLS.
- Ask your host to allow outgoing connections from your account to your mail server's IMAP and SMTP ports. On servers with cPanel/WHM, the setting is often called SMTP Restrictions.
- If your mailbox is at the same host as Perfex, use the host name your host gives for mail on that server.
06No new mail arrives
| Check | What to do |
|---|---|
| Does the cron run? | Settings and the Dashboard show "Last cron run … ago". If it never ran or the time is old, set up the cron as in Setup > Settings > Cron Job (The cron job). |
| Is the mailbox active? | Inactive mailboxes are not synced. |
| Does the mailbox show an error? | Run Test connection and fix what it reports. |
| Is the message in the Inbox folder on the server? | Only Inbox and Sent are read. Mail that a server rule or a spam filter moved to another folder does not appear. |
| Is it older than the import window? | The first import reads only the last N days (First import). |
| "This mailbox is being synced right now. Try again in a minute." | Another sync of that mailbox is in progress (cron or a colleague's Sync now). Wait a minute. |
07Large mailboxes
- A first import with many thousands of messages takes many cron runs, at 50 messages per mailbox per run by default.
- Keep the import window short (30 days is the default). Older mail stays on your server and in your normal mail program.
- You can raise Messages per mailbox per run in Settings (up to 500). Each run still stops after about 50 seconds, so a higher number helps only when your mail server is fast.
- While one mailbox imports a large backlog, mailboxes after it in name order can wait; Sync now on those mailboxes reads them at once.
- If your host stops PHP processes after a short time (for example 30 seconds), ask it to allow at least 60 seconds for the cron.
- Very large messages (over 25 MB by default) are stored with headers only; attachments over 15 MB are listed but not stored (Settings).
08Sending problems
| What you see | Cause and fix |
|---|---|
| The server answered with an error. (The message (… bytes) is larger than this mail server accepts (… bytes).) | The server's own size limit is lower than the message. Remove or shrink attachments. |
| The message would be larger than … (25 MB by default). | The attachments of this draft together exceed Max message (MB) in Settings. |
| The file is larger than … (10 MB by default). | The file exceeds Max upload (MB) in Settings. |
| The file was not received. It may be larger than the server allows. | PHP's upload_max_filesize or post_max_size is smaller than the file. |
| The server answered with an error. (… refused …) | The server refused the sender or one or more recipients and gave its reason. Nothing was sent; correct them and send again. |
| Addresses with non-English characters are refused | Version 1.0 sends to such addresses only when the SMTP server supports SMTPUTF8. |
| Message sent. The copy for the Sent folder will be saved on the server with the next sync. | The IMAP server could not be reached right after sending. The copy is saved at the next sync. |
| Message sent. No Sent folder is set for this mailbox, so no copy was saved on the server. | Map the Sent folder on the mailbox (Folder mapping). |
| This message is already being sent. | The draft is being sent. If a send was interrupted, it is released after 15 minutes. |
| This mailbox is paused or deleted. | Switch the mailbox's Active option on again. |
09Other
| What you see | Cause and fix |
|---|---|
| An attachment shows removed | It was over the size limit when the mail arrived, the retention setting deleted it, or the attachment folder was changed without moving the files. The original is still on the mail server. |
| Images are missing in an e-mail | Remote images are blocked until you click Show images. |
| A colleague cannot see a conversation | They have only View own, or cannot open that mailbox (Permissions). |
| A badge says Known contact, or no customers appear in Find a customer or lead | The conversation is linked to a record you may not see in Perfex. Staff with only Perfex View own on customers see no customers in Mail Desk (Perfex rights). |
| Restore did not bring a message back on the server | Mail Desk could not find where the server put it when it was moved (How restore finds the message), or it was moved with another mail program. Move it in your mail program. |
| "This staff member cannot open this mailbox." | That colleague cannot open the mailbox. Add them (or their role) to the shared mailbox. |
| Creating a ticket from an e-mail fails | Perfex has no ticket department yet. Create one, or choose one in Settings. |
| A conversation linked to the wrong customer | Two records share the address. Link it by hand; Mail Desk keeps a manual link (Linking by hand). |
| Messages appear read on the server although nobody read them | Syncing never sets the seen flag. Someone opened the conversation in Mail Desk, or another mail program marked it. |
10AI messages
| What you see | What to do |
|---|---|
| AI is switched off in Settings. | Tick Switch on the AI assistant in Settings (needs the Settings permission). |
| Enter an API key in Settings. / Enter a model name in Settings. | Enter the API key and the model name in Settings and save. |
| The AI provider did not accept the API key. | The key is wrong, revoked or has no credit. Create a new one at the provider. |
| The AI provider does not know this model. | Check the model name spelling exactly as the provider lists it. |
| The AI provider is rate limiting. Try again in a minute. | The provider is limiting your account. Wait, or raise the limit with the provider. |
| The monthly AI limit (… requests) is reached. / Your daily AI limit (… requests) is reached. | Mail Desk's own limit stopped the request (what counts). Raise it in Settings or wait for the next day or month. |
| The AI provider could not be reached: … | For Ollama the Perfex server must reach the Ollama server; localhost means the Perfex server itself. |
| The AI address could not be found: … | The host name in Address does not resolve. Check it. |
| This AI address points to a private network, which is not allowed for named providers. | The address for Ollama or an OpenAI-compatible endpoint resolves to a link-local address (169.254.x.x) or 0.0.0.0, which Mail Desk refuses. Use the server's real address. |
| Enter a valid address (http:// or https://) for the AI endpoint. | Correct the Address field. |
| The AI answer could not be read. Try again. | The model did not return the expected format for suggestions. Try again or use a larger model. |