Email

List emails

Changed on

List emails in a canonical folder or virtual view. Defaults to Inbox. Folder location is independent from message direction and spam verdict.

Authentication mail (OTPs / verification codes, password resets, magic links) is tagged security: "auth". Tokens without the email:auth_secrets scope see those messages with subject and body REDACTED (redacted: true) - metadata (from, date) stays visible. The subject, q and attachments filters match what the caller may read: without the scope such a message matches only on its redacted subject and body, so a query for a code it holds finds nothing.

get/api/emails/{address}/messages

Request

  • Base URL: https://domani.run
  • URL: https://domani.run/api/emails/{address}/messages
  • Auth: HTTP bearer

Path parameters

addressstring required

Mailbox email address (URL-encoded)

Query parameters

cursorstring

Pagination cursor from previous response

limitinteger

Max messages to return

direction'in' | 'out' | 'all'

Filter by direction (default: all)

folder'inbox' | 'archive' | 'sent' | 'spam' | 'trash'

System folder. Mutually exclusive with view. Defaults to inbox.

labelstring

Comma-separated labels: only messages carrying any of them

view'starred' | 'all' | 'needs_human' | 'scheduled'

Virtual view. Mutually exclusive with folder.

sincestring date-time

ISO timestamp - return only messages created after this date

untilstring date-time

ISO timestamp - return only messages created before this date

fromstring

Filter by sender address

tostring

Filter by recipient address

subjectstring

Filter by subject

qstring

Broad case-insensitive search across sender, recipients, subject, and plain-text body

unreadboolean

Return unread messages only

attachmentsboolean

Return messages that contain attachments only

spamboolean

Filter by spam flag (pass false to hide spam-flagged inbound)

Response

Message list

next_cursorstring nullable

Changes