> For the complete documentation index, see [llms.txt](https://docs.resifactory.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.resifactory.net/imap/troubleshooting.md). # Troubleshooting IMAP ## Start here: is it the connection, or the mail? One check separates the two halves of the problem. Open **App passwords** and look at **Last used** for the credential your tool is using.
The app passwords list with a last-used column
| `Last used` | What it means | Where to go | | ----------- | ---------------------------------------------------------- | ----------------------------------------------------------- | | `–`, or old | Your client has **never** successfully authenticated. | [Cannot connect](#cannot-connect) | | Recent | The client **is** connecting. The problem is what it sees. | [Connected but no mail](#connected-but-cannot-see-the-mail) | That one column resolves most of these cases in ten seconds. *** ## Cannot connect ### The port is missing from the server field **By far the most common cause with Refract.** Some clients take a single "IMAP server" string and do not append the port. In those, the value must be: ``` mail.resifactory.net:993 ```
A server field missing the port
Symptoms: hangs on connecting, times out, or fails with no specific reason. See [Refract](/imap/clients/refract.md). ### Wrong password type Your **sign-in password does not work over IMAP**. Only an [app password](/imap/app-passwords.md) does. If you no longer have the app password, you cannot read it back — revoke that one and create a replacement. ### Wrong username The username is whatever the **IMAP username** column shows for the app password you are using — usually your login email, ending `@buyers.resifactory.net`. Common slips: * Using a mailbox address (`mailbox042@…`) instead of your login email. * Using an old username after changing it on the credential. * A stray space from copy-paste. Leading and trailing spaces are ignored; a space in the middle is not. ### Wrong encryption Use **SSL/TLS on port 993**. Not STARTTLS, not port 143. There is no unencrypted option and nothing is listening on 143. ### The app password was revoked Set the status filter to **Revoked** or **All statuses** and look for it. Revoked credentials fail exactly like a wrong password. Create a new one. ### An IP allowlist is blocking you If the **CIDRs** column is not `–`, that credential only works from those ranges. A changed home IP, a VPN, or a different machine will be rejected — and it looks identical to a wrong password. Fix: connect from an allowed address, or create a credential without an allowlist. ### Rate limited Repeated failed authentication temporarily blocks further attempts from that username and IP. {% hint style="warning" %} **Stop retrying.** A client looping on a bad password keeps the block alive. Stop it, wait a few minutes, fix the credential, then try **once**. {% endhint %} ### The network in between If nothing above applies, test the path directly: ```bash openssl s_client -connect mail.resifactory.net:993 -crlf ``` A working path prints a certificate chain and then `* OK`. If it hangs or is refused, something between you and the server is blocking outbound 993 — a corporate firewall and some ISPs do this. Try another network to confirm. *** ## Connected but cannot see the mail ### The inbox window is doing its job If your client shows far fewer messages than you expected, check the **Inbox window** column on the credential.
Only messages inside the window are served
A 15-minute window means the client sees only the last 15 minutes of mail. That is correct behaviour. Widen it if you need more history: [The inbox window](/imap/inbox-window.md). Nothing is deleted — mail outside the window is still in the [web inbox](/the-console/inbox.md) and comes back the moment you widen the window. ### The credential is scoped to one batch If the **Scope** column says `batch`, that credential sees only that batch's mailboxes. Mail elsewhere is invisible to it, by design. Fix: use a unified credential, or the batch credential for that batch. See [Scopes](/imap/scopes.md). ### The mail never arrived Before blaming the client, check whether the message exists at all: open the console [Inbox](/the-console/inbox.md) and search for the sender or subject. If it is not there, no IMAP setting will produce it. Next: * Check the mailbox's status on [Accounts](/the-console/accounts.md). `expired` or `degraded` means that mailbox is not reliably fetching. * Check the message is not older than the server's retention period — shown on [Settings](/the-console/settings.md). ### Your client is looking in the wrong folder There is exactly one folder: **`INBOX`**. Clients configured to watch Sent, Archive or a custom folder will find nothing. Mail a provider filed as spam still arrives in `INBOX` here. ### Search returns nothing, or everything If a `SEARCH` comes back as `NO [CANNOT]`, you used a criterion the server does not support — it refuses rather than returning a wrong result. Rewrite the query using the supported terms in [What the server supports](/imap/capabilities.md). If a search returns far *more* than expected, check that the criterion is one the server supports and that your client is not falling back to `ALL` on error. *** ## Mail arrives, but slowly ### Not using IDLE `IDLE` is supported: new mail is pushed the moment it is stored. A client polling on a timer will always be slower than one sitting in IDLE. Turn on push / IDLE / "use push" in your client. ### The window is too wide Every command a client runs covers the window you gave it. A wide window on a busy tool makes each read heavier for no benefit. Narrow it to what the tool genuinely needs — minutes for codes, days for order tracking. See [The inbox window](/imap/inbox-window.md). ### Too many connections Several simultaneous connections on one credential do not make mail arrive sooner. One connection in IDLE is faster than five polling. *** ## Things that are working as intended
Deleting a message does nothing The `\Deleted` flag is accepted, but nothing is expunged. Use the [web inbox](/the-console/inbox.md) if you want mail actually deleted.
The client re-downloads everything after you buy more mailboxes Changing the set of mailboxes a credential can see rolls `UIDVALIDITY`, which tells clients to resync. Expected, harmless, one-off.
The client cannot create folders `CREATE`, `DELETE` and `RENAME` are refused. There is one mailbox.
Sending mail fails There is no SMTP server. Nothing here sends. Leave outgoing settings blank, or point them at a service you already use.
The message count is smaller than the number of mailboxes' mail `EXISTS` reports what that credential can see after its window and scope are applied — not your total mail. See [What the server supports](/imap/capabilities.md).
*** ## Still stuck Collect this before asking for help — it turns a long thread into one reply: * The **label** and **ID** of the app password (right-click the row → **Copy ID**). Never the password itself. * What **`Last used`** says on that row. * The client and its exact server / port / username values. * The **Inbox window** and **Scope** shown on the row. * Whether the message you expected is visible in the console [Inbox](/the-console/inbox.md). {% hint style="danger" %} Never send anyone your app password, your sign-in password, or a credential export. Nobody needs them to help you. {% endhint %} See [Getting help](/reference/support.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.resifactory.net/imap/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.