Troubleshooting
Common issues and step-by-step solutions for AgentInbox integration.
Before you start
Make sure you have a valid API key starting with
at_live_ and that your account is active.Emails not arriving
Checklist
- Ensure you are using the correct email address from the inbox.
- Make sure the inbox hasn't expired. Verify with
GET /api/v1/inboxes/{id}. - Some senders may flag temporary domains. Use a custom domain if available.
- Confirm the email is actually being sent by the service you are testing.
Wait times out
Solutions
- Some services take several minutes to send emails. Try
timeoutSeconds: 300or more. - Ensure the wait type matches the email content. For example,
otpwon't match a magic link email. - If unsure what the email contains, use
type: "email"to wait for any email.
Extraction returns low confidence
Solutions
- Set
useLlm: truefor difficult-to-parse emails. - Some senders use unusual formatting. Inspect the raw HTML body.
- A verification code might be better matched with
verification_codethanotp.
429 Rate Limit errors
Solutions
- Use exponential backoff with jitter when retrying.
- Use webhooks instead of polling for real-time updates.
- Inspect
X-RateLimit-Remainingto avoid hitting limits. - Consider upgrading to Pro for higher limits.
Retry logic example
// Exponential backoff with jitterconst delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);const jitter = Math.random() * delay;await sleep(jitter);401 Authentication errors
Solutions
- Ensure your key starts with
at_live_and is passed in theAuthorization: Bearerheader. - Make sure the API key is loaded correctly in your environment.
- If you suspect the key is compromised, regenerate it in the dashboard.
Correct authorization header
curl -X GET https://agentinbox.in/api/v1/inboxes \ -H "Authorization: Bearer at_live_..." \ -H "Content-Type: application/json"Webhooks not firing
Solutions
- Ensure the URL is publicly accessible and returns 200.
- Verify the webhook is subscribed to the events you expect.
- Use the test event feature in the dashboard.
- Review webhook delivery logs in the dashboard for errors.
Inbox quota exceeded
Solutions
- Clean up expired or unused inboxes via the API or dashboard.
- Use shorter TTLs so inboxes expire faster.
- Pro tier supports 100 active inboxes.
Delete an inbox
curl -X DELETE https://agentinbox.in/api/v1/inboxes/{id} \ -H "Authorization: Bearer $AgentInbox_API_KEY"MCP server not connecting
Solutions
- Ensure
AgentInbox_API_KEYis set in the MCP server environment. - Use
npx -y @AgentInbox/mcp-serverfor the latest version. - After updating MCP config, restart Claude, Cursor, or Windsurf.
Still stuck?
Contact support through the dashboard or check the FAQ for more answers.