sendook

Threads

Walk one conversation belonging to an agent.

A thread groups inbound messages whose In-Reply-To (or any References header) matches the Message-ID of an earlier inbound message in the same agent. Each new conversation starts a fresh thread.

Outbound messages are not yet auto-linked to threads. The send route accepts the body but doesn't read in_reply_to / references to find a matching parent. Tracked in sendook-sjq.

Get one thread

  • Method: GET
  • Path: /agents/:id/threads/:threadId
  • Auth: master key, or this agent's own per-agent key

Path parameters

ParameterTypeDescription
idstring12 lowercase alphanumeric chars (the agent id).
threadIdstring (uuid)Thread id returned in any list-messages row.

Response 200 OK

{
  "thread": {
    "id": "8b1f...uuid",
    "subject": "Question about pricing",
    "created_at": 1730000000,
    "last_activity_at": 1730000300
  },
  "messages": [
    {
      "id": "uuid-1",
      "direction": "inbound",
      "from_addr": "alice@example.com",
      "to_addr": "abc123def456@agents.yourdomain.com",
      "subject": "Question about pricing",
      "message_id_header": "<msg1@example.com>",
      "in_reply_to": null,
      "body_text": "What's the enterprise tier look like?",
      "body_html": null,
      "raw_size": 612,
      "status": "received",
      "created_at": 1730000000
    },
    {
      "id": "uuid-2",
      "direction": "inbound",
      "from_addr": "alice@example.com",
      "to_addr": "abc123def456@agents.yourdomain.com",
      "subject": "Re: Question about pricing",
      "message_id_header": "<msg2@example.com>",
      "in_reply_to": "<msg1@example.com>",
      "body_text": "Just to clarify what I meant...",
      "body_html": null,
      "raw_size": 720,
      "status": "received",
      "created_at": 1730000300
    }
  ]
}

messages is ordered by created_at ascending (oldest first). last_activity_at updates each time a new message joins the thread.

Errors

  • 401 — missing or invalid bearer.
  • 403 — per-agent key for a different agent.
  • 404 — agent unknown / tombstoned, or threadId doesn't exist for this agent.

Messages

Send mail from an agent and read its mailbox.

Webhooks

Subscribe to per-agent events; HMAC payload, retry semantics, attempt log.