Threads

A thread is a conversation: the messages you sent and the replies they drew, joined on Message-ID headers rather than on subject lines. Read a thread when you need the whole exchange in order, and list threads with awaiting_reply=true to find what someone has said that nobody has answered.

Threads are started by transactional sends, whether sent now, scheduled or held for approval, and by received mail that matches no existing thread. Marketing mail and campaigns never start or join one. How replies are matched, and why there is no fallback to subject matching, is on Receiving replies. To reply on a thread, send with thread_id and reply_to_message_id; see Replying and threads.

The thread object

List threads and Mark a thread as handled return exactly these fields. Retrieve a thread returns the same object with one more, messages, the transcript, which only retrieve carries because it can be long.

List threads

GET /v1/threads · requires threads:read

Threads in the workspace, most recently active first by last_message_at, cursor-paged as described in Pagination. The cursor is anchored on last_message_at, with the thread id breaking ties, so a thread that receives new mail while you page moves to the top of the list and is not returned again further down. To catch threads bumped during a pass, start again from the first page.

awaiting_reply=true is the query to poll when deciding what needs work. Skip the threads in it with pending_reply: true: their answer is already held for approval or scheduled, and drafting again would write it twice.

Query parameters

Example

curl "https://api.sendraven.ai/v1/threads?awaiting_reply=true" \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "a7d2e9b4-1c3f-4e5a-8b6d-0f9e8d7c6b5a",
      "subject": "Your invoice for September",
      "participants": ["ana@example.com", "billing@mail.example.com"],
      "message_count": 2,
      "awaiting_reply": true,
      "pending_reply": false,
      "handled_at": null,
      "last_message_at": "2026-09-15T12:40:00.000Z",
      "created_at": "2026-09-15T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a thread

GET /v1/threads/{id} · requires threads:read

A thread object with a messages array: every outbound and inbound message on the thread merged into one list, ordered by at, oldest first. The transcript is not paged.

Each entry has a direction of outbound or inbound, and the two carry different fields.

Outbound entries

Every message sent on this thread in this workspace, whatever its status. A draft held for approval appears as queued, a message waiting for its time as scheduled, and a message the provider refused as failed, so check status before treating an entry as something the recipient read.

Inbound entries

Received attachments are not listed in the transcript.

Trusting an inbound message

A forged sender does not show up as a FAIL. SPF checks the envelope sender, which the attacker controls, so mail from their own domain with someone else's address on the From line passes SPF, and a DKIM signature from the wrong domain reads GRAY. A false in sender_authenticated means the From line may be forged; a true means the message came from that domain and nothing more.

Path parameters

Example

curl https://api.sendraven.ai/v1/threads/a7d2e9b4-1c3f-4e5a-8b6d-0f9e8d7c6b5a \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "id": "a7d2e9b4-1c3f-4e5a-8b6d-0f9e8d7c6b5a",
  "subject": "Your invoice for September",
  "participants": ["ana@example.com", "billing@mail.example.com"],
  "message_count": 2,
  "awaiting_reply": true,
  "pending_reply": false,
  "handled_at": null,
  "last_message_at": "2026-09-15T12:40:00.000Z",
  "created_at": "2026-09-15T12:00:00.000Z",
  "messages": [
    {
      "direction": "outbound",
      "id": "3f6c1a52-8d0e-4b7a-9c21-5e4f7a9b2d10",
      "from": "Acme <billing@mail.example.com>",
      "to": ["ana@example.com"],
      "subject": "Your invoice for September",
      "text": "Hi Ana, your invoice is attached.",
      "html": null,
      "status": "delivered",
      "at": "2026-09-15T12:00:01.000Z"
    },
    {
      "direction": "inbound",
      "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a",
      "from": "ana@example.com",
      "to": ["billing@mail.example.com"],
      "subject": "Re: Your invoice for September",
      "text": "Thanks. Can you add our VAT number?",
      "raw_text": "Thanks. Can you add our VAT number?\n\nOn Tue, 15 Sep 2026 at 12:00, Acme wrote:\n> Hi Ana, your invoice is attached.",
      "html": null,
      "sender_authenticated": true,
      "spf_verdict": "PASS",
      "dkim_verdict": "PASS",
      "dmarc_verdict": "PASS",
      "spam_verdict": "PASS",
      "virus_verdict": "PASS",
      "automated": false,
      "at": "2026-09-15T12:40:00.000Z"
    }
  ]
}

Errors

Mark a thread as handled

POST /v1/threads/{id}/handled · requires emails:send

Clears awaiting_reply without sending anything, and stamps handled_at. Use it when the last message needs no answer, such as "thanks, all sorted", so the thread leaves the awaiting_reply=true list. Do not send a courtesy reply just to clear the flag; that mails a person for bookkeeping.

The next received message that is not automated sets awaiting_reply again. Calling this on a thread that is already handled succeeds and moves handled_at to now. There is no body.

Path parameters

Example

curl -X POST https://api.sendraven.ai/v1/threads/a7d2e9b4-1c3f-4e5a-8b6d-0f9e8d7c6b5a/handled \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

The thread object, with awaiting_reply false.

{
  "id": "a7d2e9b4-1c3f-4e5a-8b6d-0f9e8d7c6b5a",
  "subject": "Your invoice for September",
  "participants": ["ana@example.com", "billing@mail.example.com"],
  "message_count": 2,
  "awaiting_reply": false,
  "pending_reply": false,
  "handled_at": "2026-09-15T13:05:00.000Z",
  "last_message_at": "2026-09-15T12:40:00.000Z",
  "created_at": "2026-09-15T12:00:00.000Z"
}

Errors