Live events

GET /live-events holds the response open as server-sent events and sends one event each time the mailbox changes, so a program stays in sync without polling. It is plain HTTP, so every Nextmail SDK reads it with the client it already has, and a browser can open it with EventSource. It needs threads:read.

Each event is { id, type, occurredAt, data }, and data names the addresses it concerns, the threadId and the messageId. No content travels in the stream: read the conversation with GET /threads/{id} or the message with GET /threads/{id}/messages/{messageId} when you need it. types keeps only some kinds of event, comma separated, and address only one address.

nextmail live-events stream --types message.received

Every event carries its id as the SSE id, a number that only grows. Send the last one you handled back as the Last-Event-ID header (or lastEventId in the query) and the events you missed are replayed first, then a ready event marks the switch to live ones. The SDKs and EventSource do this on every reconnect.

• —Events can be replayed for 10 minutes and at most 1,000 back. Further back, or with an id the stream never sent, a reset event comes first: list again what you keep in sync, then carry on from the stream.
• —A comment line keeps the connection open every 25 seconds. When events you filtered out moved the stream on, it carries an id too, so a quiet filter never falls behind.
• —The server ends every stream after 30 minutes, and when the credential stops being valid, with an end event that says why. Open it again with Last-Event-ID.

An API key, the access token of an app somebody connected, or a session can open the stream. A key or an app limited to particular addresses gets only the events of the addresses it reaches, checked on the server for every event, and its stream is checked again at most once a minute while events flow, so a revoked or narrowed key stops receiving within a minute.

GET /threads/wait holds the request open for up to 60 seconds and answers the first message that arrives and matches: from the sender's address or name, subject text in the subject, address the address it was delivered to, and since the moment to look from. It is how a script or an agent waits for a sign-in code it asked a service to send. message is null when nothing matched in time, so ask again to keep waiting.

• —In the SDKs it is threads.waitForEmail, and on the command line nextmail threads wait-for-email --from service.example --subject code --timeout 60.
• —Over MCP and in the assistant it is the waitForEmail tool, read only, beside readVerificationCode for reading the code out of the message.
• —The wait wakes on the live events of the mailbox and looks again at least every 10 seconds, so a match is answered within moments of arriving.