Troubleshooting

Most SpiderMail issues come down to a mailbox connection setting or the asynchronous nature of sending. This page lists the symptoms we see most often and how to fix each one fast.

Connecting a mailbox

The POST /mail/mailboxes/{email}/test endpoint is your first tool for any connection problem — it checks IMAP and SMTP independently and returns the real error for each:

curl -X POST "https://spideriq.ai/api/v1/mail/mailboxes/alice@yourcompany.com/test" \
  -H "Authorization: Bearer $SPIDERIQ_TOKEN"
# → { "imap_ok": false, "imap_error": "authentication failed", "smtp_ok": true }

::table
Symptom | Cause | Fix
imap_ok / smtp_ok false, "authentication failed" | Using your normal password with 2FA enabled | Create an app-specific password and re-register the mailbox
"connection refused" or timeout | Wrong host or port | Re-check host/port (see Connecting a Mailbox); 993 IMAP, 587 SMTP for most providers
SMTP send works but no inbound mail | IMAP host wrong, or mailbox paused | Re-run the test; confirm the mailbox is_active is true
"Mailbox not found" on send | from_email isn't a registered mailbox | Register it first with POST /mail/mailboxes

See Connecting a Mailbox for per-provider settings.

Sending

::table
Symptom | Cause | Fix
Submit returns a job_id but no email arrives | Sending is async — you read the submit response, not the result | Poll GET /jobs/{job_id}/results until completed
Job status = failed, error mentions SMTPAuthenticationError | SMTP credentials wrong or app password needed | Fix the mailbox credentials; the error class is reported verbatim
Job failed with SMTPConnectTimeoutError | Wrong SMTP port / firewall | 465 = SSL, 587 = STARTTLS; match your provider
"Email blocked for security" | The outbound credential scanner found a secret in the body | Remove the API key / token / password from the message; see Agent Security
Reply isn't threading | Replied with a new send instead of action=reply | Use action=reply with reply_to_message_id so headers are set

Tip: A failed send returns the real exception class and message verbatim — SMTPAuthenticationError, SMTPConnectTimeoutError, etc. Read it before retrying; it tells you exactly which connection setting is wrong.

Inbox & inbound mail

::table
Symptom | Cause | Fix
New mail takes a few minutes to appear | Inbound is polled, not pushed | The poller checks each mailbox every few minutes; this is expected
A message is missing from the inbox | It may be quarantined by the security scanner | Check GET /mail/quarantine and release it if it's a false positive
Attachment text isn't there yet | Extraction runs in the background after ingest | The message appears first; extracted text follows shortly
Can't register another mailbox (403) | You've hit your plan's max_mailboxes | Delete an unused mailbox or upgrade your plan

Authentication

::table
Symptom | Cause | Fix
401 Unauthorized on every call | Token missing or malformed | Header must be Authorization: Bearer client_id:api_key:api_secret
MCP tool says "Not authenticated" | No stored credentials for the workspace | Run spideriq auth request, then retry once approved
Calls hit the wrong mailbox / workspace | Wrong workspace selected | Pass -w / --workspace (CLI) or workspace (MCP), or re-run spideriq use

Still stuck?

If the test endpoint passes but behavior is still wrong, capture the exact request, the response body, and the job_id (for sends) before reaching out — those three pin down almost any issue.

Next steps

FAQ — quick answers to common questions.
Connecting a Mailbox — provider settings and the test flow.
Agent Security — quarantine and credential blocking.