The inbox

email.message.list

GET/api/v1/households/{household_id}/queries/email.message.list

Query
Rigel runs it

Emails that came in, newest first. Filter to those that need a person (needs_you), were judged no_action or suspicious, or aren't read yet (new). text matches the subject, sender and body; from matches the sender's address. Sent mail isn't listed here; see email.draft.list and email.thread.get.

Parameters#

The inbox: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`filter`queryone of: all, needs_you, no_action, suspicious, newoptional	Which emails: all (the default), needs_you, no_action, suspicious or new (not read yet).
`text`querystringoptional	Only emails whose subject, sender or body contains this text. 1 to 200 characters
`from`querystringoptional	Only emails whose sender address contains this text, such as smithhvac.example. 1 to 254 characters
`limit`queryintegeroptional	How many to return, 1–200. Defaults to 50. 1 to 200Default `50`
`cursor`querystringoptional	The next_cursor of the previous page, with the same filters. pattern ^(\d+)\.(emm_[0-9A-HJKMNP-TV-Z]{26})$

Response#

200 The answer.

The inbox: response fields
Field	Description
`items`array of objectsrequired
`items[].id`stringrequired	A email message ID, such as emm_01JC0000000000000000000000.
`items[].email_thread_id`stringrequired	The conversation it belongs to.
`items[].from_address`stringrequired	The sender's address.
`items[].from_name`stringrequired	The sender's name; may be empty.
`items[].subject`stringrequired	The subject; may be empty.
`items[].sent_at`string (date-time)required	When it was sent.
`items[].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).
`items[].state_in_words`stringrequired	Where it stands in words, such as "Needs you" or "Not read yet".
`items[].needs_attention`booleanrequired	Whether a person has to do something about it.
`items[].summary`string or nullrequired	What it is and what Rigel did, or null if Rigel hasn't read it.
`items[].attachment_count`integerrequired	How many attachments it has.
`next_cursor`string or nullrequired	Send as cursor for the next page; null on the last page.

Errors#

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

The inbox: 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.

List the emails

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list 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_01M6V9CSR1QEHNSWX27CNZH6ZV

{
  "items": [
    {
      "id": "emm_01M6V9CSQSZJEAZ87SV36X29G7",
      "email_thread_id": "emt_01M6V9CSQSNGXN5E7SDZ614Y3Y",
      "from_address": "news@gardenweekly.example.com",
      "from_name": "Garden Weekly",
      "subject": "Ten plants for November",
      "sent_at": "2026-11-07T13:17:52.505Z",
      "state": "no_action",
      "state_in_words": "No action needed",
      "needs_attention": false,
      "summary": "A gardening newsletter. Nothing to do.",
      "attachment_count": 0
    },
    {
      "id": "emm_01M6V9CSQQA6CR44FJVKG4VBW5",
      "email_thread_id": "emt_01M6V9CSQQC4JZWYEJS090TJPS",
      "from_address": "office@riversideschool.example.com",
      "from_name": "Riverside Elementary",
      "subject": "Parent-teacher conferences, sign up by Friday",
      "sent_at": "2026-11-07T12:17:52.503Z",
      "state": "handled",
      "state_in_words": "Needs you",
      "needs_attention": true,
      "summary": "The school wants a conference time by Friday.",
      "attachment_count": 0
    },
    {
      "id": "emm_01M6V9CSQTT406KSMTSZBETKVZ",
      "email_thread_id": "emt_01M6V9CSQTWAS9BMMTQ44AST9X",
      "from_address": "pat@smithhvac.example.com",
      "from_name": "Pat Smith",
      "subject": "Furnace tune-up quote",
      "sent_at": "2026-11-07T11:17:52.506Z",
      "state": "new",
      "state_in_words": "Not read yet",
      "needs_attention": false,
      "summary": null,
      "attachment_count": 0
    },
    {
      "id": "emm_01M6V9CSQKX2C5SXSVWKC472DN",
      "email_thread_id": "emt_01M6V9CSQK00H6ZNSV7F9ENC49",
      "from_address": "office@lakeviewdental.example.com",
      "from_name": "Lakeview Dental",
      "subject": "Reminder: Nia's cleaning on Thursday",
      "sent_at": "2026-11-07T10:17:52.499Z",
      "state": "handled",
      "state_in_words": "Handled",
      "needs_attention": false,
      "summary": "A reminder for Nia's cleaning on Thursday at 3:30 pm. It's already on the calendar.",
      "attachment_count": 0
    }
  ],
  "next_cursor": null
}

Only emails that need you

filter is all, needs_you, no_action, suspicious or new.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?filter=needs_you' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?filter=needs_you 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_01M6V9CSR3GY6QQKAPKT1T0K50

{
  "items": [
    {
      "id": "emm_01M6V9CSQQA6CR44FJVKG4VBW5",
      "email_thread_id": "emt_01M6V9CSQQC4JZWYEJS090TJPS",
      "from_address": "office@riversideschool.example.com",
      "from_name": "Riverside Elementary",
      "subject": "Parent-teacher conferences, sign up by Friday",
      "sent_at": "2026-11-07T12:17:52.503Z",
      "state": "handled",
      "state_in_words": "Needs you",
      "needs_attention": true,
      "summary": "The school wants a conference time by Friday.",
      "attachment_count": 0
    }
  ],
  "next_cursor": null
}

Search the emails for conferences

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?text=conferences' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?text=conferences 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_01M6V9CSR4S5PE8571X0HJYAN9

{
  "items": [
    {
      "id": "emm_01M6V9CSQQA6CR44FJVKG4VBW5",
      "email_thread_id": "emt_01M6V9CSQQC4JZWYEJS090TJPS",
      "from_address": "office@riversideschool.example.com",
      "from_name": "Riverside Elementary",
      "subject": "Parent-teacher conferences, sign up by Friday",
      "sent_at": "2026-11-07T12:17:52.503Z",
      "state": "handled",
      "state_in_words": "Needs you",
      "needs_attention": true,
      "summary": "The school wants a conference time by Friday.",
      "attachment_count": 0
    }
  ],
  "next_cursor": null
}

Emails from one sender

from matches the sender's address or name.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?from=lakeviewdental.example.com' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?from=lakeviewdental.example.com", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?from=lakeviewdental.example.com 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_01M6V9CSR5XNQ4X0KGVBJ9GN6K

{
  "items": [
    {
      "id": "emm_01M6V9CSQKX2C5SXSVWKC472DN",
      "email_thread_id": "emt_01M6V9CSQK00H6ZNSV7F9ENC49",
      "from_address": "office@lakeviewdental.example.com",
      "from_name": "Lakeview Dental",
      "subject": "Reminder: Nia's cleaning on Thursday",
      "sent_at": "2026-11-07T10:17:52.499Z",
      "state": "handled",
      "state_in_words": "Handled",
      "needs_attention": false,
      "summary": "A reminder for Nia's cleaning on Thursday at 3:30 pm. It's already on the calendar.",
      "attachment_count": 0
    }
  ],
  "next_cursor": null
}

List the first two emails

next_cursor says there are more.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?limit=2' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

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

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?limit=2 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_01M6V9CSR6EVMRKJ7DYJJDZW28

{
  "items": [
    {
      "id": "emm_01M6V9CSQSZJEAZ87SV36X29G7",
      "email_thread_id": "emt_01M6V9CSQSNGXN5E7SDZ614Y3Y",
      "from_address": "news@gardenweekly.example.com",
      "from_name": "Garden Weekly",
      "subject": "Ten plants for November",
      "sent_at": "2026-11-07T13:17:52.505Z",
      "state": "no_action",
      "state_in_words": "No action needed",
      "needs_attention": false,
      "summary": "A gardening newsletter. Nothing to do.",
      "attachment_count": 0
    },
    {
      "id": "emm_01M6V9CSQQA6CR44FJVKG4VBW5",
      "email_thread_id": "emt_01M6V9CSQQC4JZWYEJS090TJPS",
      "from_address": "office@riversideschool.example.com",
      "from_name": "Riverside Elementary",
      "subject": "Parent-teacher conferences, sign up by Friday",
      "sent_at": "2026-11-07T12:17:52.503Z",
      "state": "handled",
      "state_in_words": "Needs you",
      "needs_attention": true,
      "summary": "The school wants a conference time by Friday.",
      "attachment_count": 0
    }
  ],
  "next_cursor": "1794053872503.emm_01M6V9CSQQA6CR44FJVKG4VBW5"
}

List the next emails

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?limit=2&cursor=1794053872503.emm_01M6V9CSQQA6CR44FJVKG4VBW5' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?limit=2&cursor=1794053872503.emm_01M6V9CSQQA6CR44FJVKG4VBW5", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.message.list?limit=2&cursor=1794053872503.emm_01M6V9CSQQA6CR44FJVKG4VBW5 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_01M6V9CSR7BPSAYA1A24Z1S58Y

{
  "items": [
    {
      "id": "emm_01M6V9CSQTT406KSMTSZBETKVZ",
      "email_thread_id": "emt_01M6V9CSQTWAS9BMMTQ44AST9X",
      "from_address": "pat@smithhvac.example.com",
      "from_name": "Pat Smith",
      "subject": "Furnace tune-up quote",
      "sent_at": "2026-11-07T11:17:52.506Z",
      "state": "new",
      "state_in_words": "Not read yet",
      "needs_attention": false,
      "summary": null,
      "attachment_count": 0
    },
    {
      "id": "emm_01M6V9CSQKX2C5SXSVWKC472DN",
      "email_thread_id": "emt_01M6V9CSQK00H6ZNSV7F9ENC49",
      "from_address": "office@lakeviewdental.example.com",
      "from_name": "Lakeview Dental",
      "subject": "Reminder: Nia's cleaning on Thursday",
      "sent_at": "2026-11-07T10:17:52.499Z",
      "state": "handled",
      "state_in_words": "Handled",
      "needs_attention": false,
      "summary": "A reminder for Nia's cleaning on Thursday at 3:30 pm. It's already on the calendar.",
      "attachment_count": 0
    }
  ],
  "next_cursor": null
}

For Rigel#

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