Read email threads without losing conversation context

Read the conversation before deciding

A thread is the useful unit when the latest email depends on an earlier promise, attachment or decision. Listing threads gives you a bounded overview; fetching one thread gives you its messages in ascending order. The detail field is messages, not emails. Preserve that distinction in your client types so an empty array caused by a wrong property name cannot masquerade as an empty conversation. Start with the task the user asked for, then select the relevant thread rather than loading the entire mailbox into the model.

Fetch through the inbox boundary

Use GET /v0/emails/inboxes/:inbox_id/emails/threads/:thread_id. The inbox route makes ownership explicit and works well with a credential restricted to that inbox. Save both identifiers in your job record, because a thread ID copied from another workspace is not authority to read it. A 404 can represent a missing or inaccessible resource; do not infer that another customer has no such conversation. Org-level and project-level thread routes support broader views when the authorized workflow actually needs them. They do not remove the scope of the calling key.

curl --fail-with-body "https://api.lupin.sh/v0/emails/inboxes/$INBOX_ID/emails/threads/$THREAD_ID" \
  -H "Authorization: Bearer $LUPIN_API_KEY"

Separate chronology from interpretation

Build a compact timeline containing each message ID, timestamp, sender, recipients and the relevant new text. Message objects expose preview and extracted_text, with quoted replies stripped from the latter, alongside other message fields. Extraction helps reduce duplicated context but can omit information that matters, so retrieve the original message or raw source when a disputed quotation needs checking. Record which message supports each important fact. A subject line such as Re: contract does not prove that a later message accepted the terms discussed earlier.

Handle access and label boundaries

Spam, blocked, unauthenticated and trash labels have separate read gates. A thread that appears incomplete to a restricted key may reflect a policy boundary, rather than a transport failure. Search excludes gated labels and cannot be used as a universal inventory of every stored message. Report the scope and filters of your lookup when absence matters. If the task requires incident investigation across quarantined mail, obtain an appropriately authorized read path instead of relabeling messages or broadening the worker credential simply to make a summary look complete.

Produce a reviewable handoff

Return the latest request, unresolved questions and any proposed next step with their source message IDs. Distinguish the sender’s statements from verified account facts or a human’s actual authorization. An inbound request to refund a payment is context for review, not permission to run a payment tool. If the next action is a reply, prepare a draft tied to the source message and show its eventual recipients. Your next implementation step is a fixture with two replies that quote earlier messages, so your summary can demonstrate it preserves new information without repeating the entire chain.

Handle stale source references

If a saved thread is deleted or the delegated key loses access, mark the work item’s source unavailable. Do not search by its subject and silently substitute another conversation. A case can preserve its prior summary as historical derived content, but the agent should identify that it cannot currently verify the source before proposing another externally visible response.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

• Lupin threads ↗Checked 2026-11-05
• Lupin messages ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.