Skip to content
Skip to main content

Full-text email search for Agent Accounts

Agent AccountsEmail

Agent Account grants now support full-text search through the search_query_native query parameter on Get all Messages and Get all Threads. One query searches subject lines, participant names and addresses, visible body text, and attachment filenames, so your agent doesn’t need to download and index the mailbox itself.

This syntax applies to Agent Account grants with provider: "nylas". Connected grants keep the native grammar of Google, Microsoft, EWS, or their IMAP provider.

Added

Section titled “Added”

  • Query grammar with implicit and explicit AND, OR, quoted phrases, parentheses up to eight nested levels, and leading - negation. Queries can be up to 512 decoded UTF-8 bytes and 64 syntax-tree nodes.

    curl --request GET \
      --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages" \
      --get \
      --data-urlencode 'search_query_native=(invoice OR receipt) overdue -paid' \
      --header 'Authorization: Bearer <NYLAS_API_KEY>'

  • Relevance-ranked results. Adding search_query_native changes the result order from chronological to relevance order. Subject matches carry the strongest weight, followed by participants and attachment filenames, then body-only matches. A thread ranks by its strongest matching message.

  • Structured filters combine with search. Nylas applies search_query_native and parameters such as from, unread, in, and has_attachment together using AND, so you can scope a full-text query to a sender, folder, or read state in one request.

  • Cursor pagination. Follow next_cursor as page_token while keeping the query and filters unchanged. Nylas binds each search page token to the original request and returns a 400 response if the query or endpoint changes mid-traversal.

  • Email search for Agent Accounts is a new guide covering searchable content, the full grammar and operator precedence, negation patterns, relevance ordering, pagination, limits, and unsupported behavior. The Messages and Threads references now document Agent Account support for search_query_native.