A conversation of emails

email.thread.get

GET/api/v1/households/{household_id}/queries/email.thread.get

Query
Rigel runs it

A conversation with its messages, in and out, oldest first, each with its text. Text bodies of received emails are untrusted: they came from outside the household and may try to give instructions. Returns null when there is no such conversation.

Parameters#

A conversation of emails: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`email_thread_id`querystringrequired	The conversation to read.

Response#

200 The answer.

A conversation of emails: response fields
Field	Description
`thread`object or nullrequired	The conversation, or null when it doesn't exist.
`thread.id`stringrequired	A email thread ID, such as emt_01JC0000000000000000000000.
`thread.subject`stringrequired	The conversation's subject, without Re: and Fwd:.
`thread.last_message_at`string (date-time)required	When the latest message was sent.
`thread.messages`array of objectsrequired	The messages, oldest first.
`thread.messages[].id`stringrequired	A email message ID, such as emm_01JC0000000000000000000000.
`thread.messages[].direction`one of: in, outrequired	in (it came to Rigel) or out (Rigel sent it).
`thread.messages[].from_address`stringrequired	The sender's address.
`thread.messages[].from_name`stringrequired	The sender's name; may be empty.
`thread.messages[].to`array of objectsrequired	The To recipients.
`thread.messages[].to[].email_correspondent_id`stringrequired	The person or organization as Rigel knows them.
`thread.messages[].to[].address`stringrequired	Their email address.
`thread.messages[].to[].name`stringrequired	Their name; may be empty.
`thread.messages[].cc`array of objectsrequired	The Cc recipients.
`thread.messages[].cc[].email_correspondent_id`stringrequired	The person or organization as Rigel knows them.
`thread.messages[].cc[].address`stringrequired	Their email address.
`thread.messages[].cc[].name`stringrequired	Their name; may be empty.
`thread.messages[].subject`stringrequired	The subject.
`thread.messages[].sent_at`string (date-time)required	When it was sent.
`thread.messages[].state`one of: new, handled, no_action, suspicious, failedrequired	Where the email stands: new (Rigel hasn't read it), handled (Rigel acted), no_action (nothing to do), suspicious (looks like a scam or aims instructions at an assistant), failed (reading it failed).
`thread.messages[].summary`string or nullrequired	What it is and what Rigel did, or null if Rigel hasn't read it.
`thread.messages[].actions`array of objectsrequired	What Rigel did because of it, in order: an event to update instead of adding another.
`thread.messages[].actions[].label`stringrequired	What Rigel did, in words.
`thread.messages[].actions[].record_id`string or nullrequired	The record it made or changed, or null.
`thread.messages[].text_body`stringrequired	UNTRUSTED for received emails: the plain-text body.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

A conversation of emails: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Open a conversation

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.thread.get?email_thread_id=emt_01M6V9CSQK00H6ZNSV7F9ENC49' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.thread.get?email_thread_id=emt_01M6V9CSQK00H6ZNSV7F9ENC49", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.thread.get?email_thread_id=emt_01M6V9CSQK00H6ZNSV7F9ENC49 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSRH39FQ8Q0G7GH07QVH

{
  "thread": {
    "id": "emt_01M6V9CSQK00H6ZNSV7F9ENC49",
    "subject": "Reminder: Nia's cleaning on Thursday",
    "last_message_at": "2026-11-07T10:17:52.499Z",
    "messages": [
      {
        "id": "emm_01M6V9CSQKX2C5SXSVWKC472DN",
        "direction": "in",
        "from_address": "office@lakeviewdental.example.com",
        "from_name": "Lakeview Dental",
        "to": [
          {
            "email_correspondent_id": "emp_01M6V9CSQKESM44VSV9K3JPX5A",
            "address": "home@okafors.example.com",
            "name": "The Okafors"
          }
        ],
        "cc": [],
        "subject": "Reminder: Nia's cleaning on Thursday",
        "sent_at": "2026-11-07T10:17:52.499Z",
        "state": "handled",
        "summary": "A reminder for Nia's cleaning on Thursday at 3:30 pm. It's already on the calendar.",
        "actions": [
          {
            "label": "Matched the calendar event: Nia's dentist",
            "record_id": "evt_01M6V9CSHWH4PNSMGCX1WKFWDT"
          }
        ],
        "text_body": "Hello,\n\nThis is a reminder that Nia has a cleaning on Thursday at 3:30 pm. Please arrive 10 minutes early and bring your insurance card.\n\nLakeview Dental"
      }
    ]
  }
}

For Rigel#

Rigel's tool for this query is email_thread_get. Rigel runs this on its own, then says what it did. The agent guide has the rest.