Originally published at lumbox.co
Resend coined Agent Experience — AX — as the agent-first parallel to DX. The idea: APIs designed for humans reading docs on a Tuesday afternoon look different from APIs designed for LLMs calling tools in a tight loop. For email APIs, the gap is huge.
What bad AX looks like in email APIs
- Polling required. Agent burns tokens checking "any new mail?" every 5 seconds.
- Raw MIME. Agent has to parse multipart boundaries before it can read the body.
- No first-class OTP field. Agent runs regex on HTML to find the code.
-
Opaque errors. Agent gets
"500: internal error"with no recovery guidance. - No idempotency. Agent retries and sends duplicates.
What good AX looks like
- Long-poll endpoints. One call, blocks until event or timeout.
- Structured extraction. OTP, links, attachments, category — all as first-class JSON fields.
-
Typed errors.
{"error": "timeout", "retryable": true, "wait_ms": 5000}. - Idempotency keys. Every mutating endpoint accepts one.
- MCP-native. Tools are discoverable via a manifest, not scraped from HTML docs.
- Machine-readable docs. OpenAPI + .well-known/agent-skills + llms.txt.
Lumbox's take
Every Lumbox endpoint was designed with a question: "how would a tool-calling LLM invoke this?" That's why waitForOtp exists instead of a listMessages + filter pattern. It's why responses include otp, links, and category alongside the raw body. It's why we publish an MCP server on day one.
AX isn't a checkbox. It's the shape of the whole API surface. lumbox.co.
