API reference / Threads

List threads

List threads filtered by labels or triage of the latest message. A sent reply clears the thread triage until a new incoming message arrives.

GET/v1/inboxes/{inboxId}/threads

Requires an API key with the messages:read scope. MCP tool: list_threads. CLI: goshenemail threads list.

Request

Name	Type	Required	Notes
`inboxId`	`string (email)`	Yes	up to 254 characters

Name	Type	Notes
`category`	`"billing" \| "support" \| "sales" \| "personal" \| "notification" \| "other"`
`needsReply`	`"yes" \| "no" \| "uncertain"`
`urgency`	`"low" \| "normal" \| "high" \| "critical"`
`limit`	`integer`	1–100, default 20
`pageToken`	`string`	up to 200 characters
`labels`	`string[]`	up to 50 items
`includeTrash`	`boolean`	default false

Field	Type	Notes
`threads`	`object[]`
`threadId`	`string`
`inboxId`	`string`
`subject`	`string`
`preview`	`string`
`timestamp`	`string`
`triage`	`object \| object \| object`
`status`	`string`
`code`	`"provider_unavailable" \| "provider_rejected" \| "invalid_response"`
`failedAt`	`string (ISO 8601)`
`version`	`number`
`model`	`string`	1–100 characters
`analyzedAt`	`string (ISO 8601)`
`durationMs`	`integer`	at least 0
`bodyTruncated`	`boolean`
`usage`	`object`
`category`	`object`
`needsReply`	`object`
`urgency`	`object`
`messageCount`	`number`
`labels`	`string[]`
`senders`	`string[]`
`recipients`	`string[]`
`receivedTimestamp`	`string`
`sentTimestamp`	`string`
`lastMessageId`	`string`
`attachmentCount`	`number`
`nextPageToken`	`string`

Errors return { "error": { "code", "message", "transient" } } with a 4xx or 5xx status. See Errors.

curl "https://api.goshenemail.com/v1/inboxes/research%40agents.goshenemail.com/threads" \
  -H "Authorization: Bearer $GOSHENEMAIL_API_KEY"

goshenemail threads list --inbox-id "research@agents.goshenemail.com"