List email messages

org.intentschema.communication.email.message.list.v1

JSON: bare · @sha256:0ef05293f1c2…
Hash: sha256:0ef05293f1c2eaf0da45b9e49fac69534ca7aad5cccff2475a807d2d26706b5e

Searches a user's mailbox and returns message summaries matching the given query and structured filter.

Payload

FieldTypeDescription
target *Target
objectobject
object
FieldTypeDescription
querystringProvider-specific search string (Gmail syntax, JMAP filter string, Outlook KQL). Applied alongside `filter` if both are provided.
filterobjectStructured filter, JMAP-inspired.
limitinteger (minimum 1; maximum 500; default 50)
cursorstringOpaque pagination cursor returned by a prior search.
filter
FieldTypeDescription
fromstring
tostring
subjectstring
bodystring
has_attachmentboolean
is_unreadboolean
afterstring (date-time)
beforestring (date-time)
labels_anystring[]
labels_allstring[]

Result

FieldTypeDescription
messages *object[]
next_cursorstringPresent when more results are available.
estimated_totalintegerOptional provider estimate of total matches.
messages[]
FieldTypeDescription
external_id *string
thread_idstring
fromstring (email)RFC 5321 mailbox. Plain address (jane@example.com) or with display name ("Jane Doe" <jane@example.com>).
tostring (email)[]
subject *string
snippetstringShort plaintext preview of the body.
datestring (date-time)
labelsstring[]
is_unreadboolean
has_attachmentsboolean

Examples

query-string search

{
  "target": {
    "system": "gmail"
  },
  "object": {
    "query": "from:jane@example.com is:unread",
    "limit": 20
  }
}

structured filter with pagination

{
  "target": {
    "system": "gmail"
  },
  "object": {
    "filter": {
      "from": "jane@example.com",
      "has_attachment": true,
      "after": "2026-01-01T00:00:00Z"
    },
    "limit": 50,
    "cursor": "opaque-cursor-from-prior-result"
  }
}

Profiles