API reference / Messages

List messages

List messages, optionally filtered by category, needsReply (yes/no/uncertain), and urgency. Triage describes each incoming message at arrival; it does not authorize actions. Pass nextPageToken as pageToken.

GET/v1/inboxes/{inboxId}/messages

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

Request

Path parameters

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

Query parameters

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

Response

Field	Type	Notes
`messages`	`object[]`
`messageId`	`string`
`threadId`	`string`
`inboxId`	`string`
`from`	`string`
`to`	`string[]`
`subject`	`string`
`preview`	`string`
`timestamp`	`string`
`labels`	`string[]`
`attachments`	`object[]`
`attachmentId`	`string`
`filename`	`string`
`contentType`	`string`
`size`	`number`
`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`
`protection`	`object`
`status`	`"clean" \| "quarantined" \| "released"`
`scannedAt`	`string (ISO 8601)`
`authentication`	`object`
`spam`	`object`
`antivirus`	`object`
`reasons`	`"malware" \| "spam" \| "authentication_failed" \| "scan_incomplete"[]`	up to 4 items
`releasedAt`	`string (ISO 8601)`
`releasedBy`	`string`	1–200 characters
`text`	`string`
`html`	`string`
`cc`	`string[]`
`bcc`	`string[]`
`replyTo`	`string[]`
`delivery`	`object`
`version`	`number`
`sentAt`	`string`
`updatedAt`	`string`
`recipients`	`object[]`
`nextPageToken`	`string`

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

Examples

curl

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

CLI

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