Skip to main content
A thread is a single conversation — all the messages that belong to one back-and-forth exchange between your agent and a recipient. Sentvia reconstructs threads automatically from standard RFC-5322 email headers (Message-ID, In-Reply-To, and References), so the conversation stays coherent whether your agent is replying or a recipient is responding from their own mail client.

​
List threads

To see all threads for a given inbox, send a GET request to /threads with the inbox_id query parameter. Results are ordered by most recent activity. 
curl "https://sentvia-api-production.up.railway.app/v1/threads?inbox_id=INBOX_ID&limit=25" \
  -H "Authorization: Bearer sv_live_…"
Response
{
  "threads": [
    {
      "id": "t_…",
      "inbox_id": "b1f2…",
      "subject": "Order #4821",
      "last_message_at": "2026-06-26T14:32:00Z"
    }
  ]
}

​
Read a full thread

GET /threads/{id} returns the complete conversation in chronological order — oldest message first — with all message bodies and attachment metadata inlined. Use this endpoint when your agent needs the full context of a conversation before composing a reply. 
curl "https://sentvia-api-production.up.railway.app/v1/threads/THREAD_ID" \
  -H "Authorization: Bearer sv_live_…"
Response
{
  "id": "t_…",
  "subject": "Order #4821",
  "messages": [
    {
      "id": "m_1",
      "direction": "inbound",
      "from_addr": "jane@acme.com",
      "body_text": "Where's my order?",
      "attachments": []
    },
    {
      "id": "m_2",
      "direction": "outbound",
      "from_addr": "support-bot@mail.sentvia.ai",
      "body_text": "On its way — tracking attached.",
      "attachments": [
        {
          "filename": "tracking.pdf",
          "content_type": "application/pdf",
          "url": "https://…"
        }
      ]
    }
  ]
}

​
Fetch a single message

If you only need one message rather than the whole thread, use GET /messages/{id}. The response includes the current delivery_status, any attachments with short-lived signed download URLs, and any labels applied to the message. 
curl "https://sentvia-api-production.up.railway.app/v1/messages/MESSAGE_ID" \
  -H "Authorization: Bearer sv_live_…"
Signed attachment URLs expire after a short window. Fetch the attachment content promptly after retrieving the message, rather than storing the URL for later use.

​
Keep replies in-thread

When you use the /reply or /forward endpoints, Sentvia sets the In-Reply-To and References headers for you automatically — the reply lands in the correct thread in both Sentvia and the recipient’s mail client. If you send a fresh POST /messages that should join an existing thread rather than start a new one, pass the in_reply_to and references values from the message you are answering. 
curl -X POST https://sentvia-api-production.up.railway.app/v1/messages \
  -H "Authorization: Bearer sv_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_id": "INBOX_ID",
    "to": ["jane@acme.com"],
    "subject": "Re: Order #4821",
    "text": "Your order shipped this morning.",
    "in_reply_to": "<original-message-id@mail.sentvia.ai>",
    "references": "<original-message-id@mail.sentvia.ai>"
  }'
Always use the /reply endpoint when responding to an inbound message your agent received — it handles all the header plumbing for you. Reserve manual in_reply_to / references for cases where you are constructing a message programmatically that needs to join a thread you did not receive through Sentvia.