Use a long poll when an active agent workflow is already waiting for a verification message, and use a webhook when arriving mail should trigger separate asynchronous processing. Lumbox supports both patterns, including an OTP retrieval request that waits up to 120 seconds and email-received webhook notifications.
The decision depends on who owns the wait. A browser task sitting on a login challenge already has an active attempt and a place to put the result. A background email processor may have no browser session running at all. These are different orchestration needs even if the incoming message looks the same.
Neither mechanism removes the need to associate mail with a customer account. A webhook can notify you of a message faster than your application understands what to do with it. A waiting request can return a valid code for the wrong overlapping attempt if the routing design is ambiguous.
Compare the application work
| Question | Long poll | Webhook |
|---|---|---|
| Who starts the interaction? | The waiting application | The service delivering an event |
| What does your runtime maintain? | An open request and active attempt state | A receiving endpoint and event-processing state |
| Natural fit | A browser paused at a verification step | Mail that wakes or updates a separate workflow |
| Important failure path | Client or server timeout | Delivery failure or repeated event handling |
| Correlation owner | Your application | Your application |
A long poll is often a small first integration because it uses an ordinary request from the workflow already doing the login. A webhook can fit an existing event-driven system well. The table is an architectural comparison, not a performance benchmark or a claim that either approach is universally cheaper.
Understand the two Lumbox wait endpoints
GET /v1/inboxes/:id/otp returns a compact code response from suitable verification mail. GET /v1/inboxes/:id/wait returns a formatted email response. Both default to a 30-second timeout and allow up to 120 seconds, but their default freshness behavior differs.
The OTP route defaults to a five-minute lookback. The wait route defaults to the time the request starts. If mail arrives before a /wait request and you rely on the default, that message may be outside the search window. When using REST for a known attempt, set since deliberately. See the API reference.
The wait route accepts filters including sender, subject, category and has_otp. It marks a returned email read. The OTP shortcut looks for the verification category and extracted codes. Marking mail read is not the same as reserving it for exactly one workflow, so do not use read state as your only duplicate-processing control.
Budget the complete request lifetime
If the server can wait 120 seconds but your HTTP client times out after 30, the application sees a client failure before the server’s retrieval window ends. Reverse proxies and task runtimes can impose their own limits too. Configure the whole path for the intended wait.
For example, a 120-second server wait with a 130-second client timeout gives a small transport margin. That is an example configuration, not a latency guarantee. It does not mean email always arrives within two minutes or that the portal keeps a code valid for that long.
When the browser run is canceled, stop or disregard the outstanding retrieval result as appropriate for your client. A response arriving after cancellation should not silently revive an old login attempt. The code and the browser session need the same application owner.
What “no client polling loop” means
With the OTP endpoint, your application can make one request instead of repeatedly asking for new mail. The server still checks its database once per second. Describing the system as having no polling anywhere would be inaccurate.
This matters for buyers comparing implementations. The useful claim is about the interface you integrate: a bounded request returns a parsed result or times out. It is not an assertion about zero database work, instantaneous delivery or unlimited concurrency.
The parser is also part of that contract. A message must arrive, match the filters and satisfy the route’s code requirements. If the exact forwarded portal template is not recognized, increasing the wait duration alone will not solve that mismatch.
Where webhooks fit
Lumbox’s webhook guide documents registering an endpoint for email.received events. The event gives your application a way to react to incoming mail without leaving a particular caller waiting on a request.
That can suit a system where many workflows are suspended in durable storage and resumed when a relevant event arrives. Your receiver maps the inbox and message to an application record, validates the event according to the service’s current contract, and schedules the next step.
Build the receiver so repeated processing does not cause repeated browser submissions or duplicate replies. This is a recommendation for your application, not a claim that the inspected endpoint provides exactly-once delivery. Verify the current signing, retry and payload behavior before relying on those details in production.
Handle timeout and resend separately
The OTP endpoint returns HTTP 408 when it finds no suitable code before timeout. The wait endpoint also returns HTTP 408 when no matching email is returned within its window. Preserve the status and the stage in your diagnostic record.
A second retrieval request and a request for the portal to send another code are different actions. The former looks for mail. The latter can create a new challenge or invalidate an earlier value, depending on the portal. Your workflow should make that choice explicitly.
For a controlled pilot, test a late message, an early message, an unsuitable template and a canceled attempt. Include a scenario where the portal sends a second code. Record which message each path selected and whether the browser accepted it.
Choose the first implementation you can explain
If your browser controller can keep a bounded request open, start with the OTP route and a single test inbox. If your product already has event ingestion and durable workflow state, a webhook may fit that structure better. You can change the orchestration without changing the basic need for correct routing and attempt ownership.
Implementation references: apps/api/src/routes/inboxes.ts for both long-poll handlers, apps/docs/content/docs/webhooks.mdx for the public webhook interface, and apps/api/src/utils/parser.ts for code extraction. Source checked October 3, 2026; no throughput or delivery-latency result is claimed.
Kumar