Troubleshooting and limits
Resolve connection failures, missing tools, API errors, and quota limits.
Start with the step that failed. A working dashboard login, an approved agent connection, and a working mailbox connection are separate checks.
Sign-in and mailbox connections
| Problem | What to do |
|---|---|
| An account with your email already exists | Sign in or reset your password. If you have not verified your email, request a new verification link. |
| Verification or reset link expired | Request a new link from the verification or password-recovery page. Links expire after one hour. |
| Google or Microsoft is not configured | Ask the Cloud operator to enable the provider. Self-hosted provider settings don't configure Cloud. |
| Provider consent is blocked | Check the account you selected and your organization's administrator restrictions. |
| IMAP or SMTP login fails | Check both servers, your username, and whether the provider requires an app password. Cloud validates both services before saving. |
| Mailbox authorization expired or was revoked | Reconnect the mailbox, then ask your agent to list your 5 most recent emails. |
See connect mailboxes for server settings and account settings for recovery.
MCP connection and tools
If fluxmail-cloud does not appear, check the configuration file for your client, enable the server, and restart or reload it. The client needs Streamable HTTP and OAuth, or a custom bearer header for key authentication.
For OAuth, start sign-in again if the request expired, the connection was revoked, or refresh failed. Codex must use dynamic registration (--oauth-client-registration dcr); in Claude Desktop or Claude on the web, choose Register automatically. Cloud does not support Client ID Metadata Documents. If a key-authenticated connection fails, check that the key is still active and that the client process can read its secret. Environment-variable syntax differs between clients. After changing a launch environment, restart the app; changing an export in another terminal does not update it.
If the server connects but tools are missing, compare them with the connection's scopes. Cloud advertises only permitted tools. A tool can still fail if the connection has no access to the requested mailbox.
Opening /mcp in a browser sends a GET request and can return 405. This is expected: Cloud's MCP endpoint handles POST requests from an MCP client.
Listing tools verifies the MCP connection. With mail.read, call list_accounts and then list_emails with the intended accountId, pageSize: 5, and includeSnippet: false to verify access by listing your 5 most recent emails. Listing tools or accounts alone does not complete the dashboard's agent onboarding check.
Errors and retries
REST failures include error.code, error.message, and a requestId. The x-request-id header also identifies the request. Keep that ID when asking for help; leave credentials and message contents out of logs.
MCP tool failures set isError and return the error under structuredContent.error.
| Response | What to check |
|---|---|
| 400 | Argument names, required IDs, valid recipients, and provider restrictions |
| 401 | Missing, expired, or revoked agent authorization; an auth_expired provider error means reconnect the mailbox |
402 subscription_required | Ask the workspace owner to check Billing for an expired trial or suspended subscription |
| 403 | Required scope and workspace access; seat_required means the workspace lacks member capacity, and entitlement_exceeded means the mailbox exceeds its plan limit |
| 404 | Mailbox grants or a resource that is no longer available |
409 entitlement_exceeded | Check the error message: the workspace may have reached its mailbox limit or its combined limit of 100 active agent keys and OAuth connections, or the provider may have an entitlement restriction. Review plan capacity, remove unused connections or authorizations, or check the provider's requirements. |
| 409 send conflict or uncertain submission | Check send status before retrying |
| 413 | Request or decoded attachment size |
429 busy or mailbox_busy | Temporary capacity or another mailbox operation; honor Retry-After and retry read-only calls with backoff |
429 rate_limited | Check whether the workspace's hourly allowance or the provider's rate limit was reached |
503 billing_unavailable | Cloud could not verify billing; retry later or ask the workspace owner to check Billing |
| Provider failure | Reconnect if authorization has expired; otherwise check provider availability |
For workspace rate limits, wait for the next UTC hour. For provider rate limits, follow the provider's recovery guidance. Send retries must follow sending and retries, including after a timeout or temporary HTTP failure.
Limits
| Resource | Limit |
|---|---|
| Connected mailboxes | Pro: 10; Business: 20 per purchased member, pooled across the workspace |
| Active OAuth connections and agent keys | 100 combined per workspace |
| OAuth access-token lifetime | 15 minutes |
| OAuth refresh inactivity / absolute grant limit | 30 days / 90 days |
| Agent-key lifetime | 90 days by default; choose 7, 30, 90, or 365 days, or Never |
| API calls | 1,000 per workspace per UTC hour, including MCP protocol requests |
| New send attempts | 20 per workspace per UTC hour |
| Search page size | 25 by default; 1 to 100 per request |
Each downloaded attachment and the total attachments in a send can contain up to 10,000,000 decoded bytes. Downloads return base64 content.
See billing and plans for trials, subscription access, and payment recovery, or workspaces and members for invitations and capacity. Scheduled sends and remote CLI configuration are not available in Cloud.
Last updated