Version:
Only show these results:

Searching with Nylas

Depending on the number of authenticated users your project has, Nylas might return a lot of data for "Get all" requests. This page explains how you can search and filter end-user data.

How searching works in Nylas v3

Generally, filtering for data in Nylas follows this flow:

  1. Determine the query parameters you plan to use.
  2. Make a "Get all" request (for example, Get all Messages) with your query parameters.
  3. Inspect the results to find the ID of the object that you want to work with.

🔍 Nylas offers query parameters to help you sort through pages of results, and to limit the number of results returned. For more information, see Filter using query parameters and Reduce response size with field selection.

For more information about a specific object, you can make a GET request with the object ID (for example, GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>).

Changes to search in Nylas v3

  • The v2 GET /messages/search and GET /threads/search endpoints are deprecated.
  • You can now use query parameters to define your search terms in "Get all" requests (for example, Get all Messages).
  • You can now use the search_query_native parameter to define provider-specific search strings for messages and threads on Google, Microsoft Graph, IMAP, and EWS.

For more information about changes in v3, see the v3 diff view.

Search for grants

Nylas supports the following standard query parameters for Get all Grants requests:

  • before, since
  • grant_status, email, provider, ip
  • account_id, account_ids

📝 account_id and account_ids are populated for grants created during the v2-to-v3 migration process only. For all other grants, these fields are blank.

Search for calendars

Calendars are tied to a user's grant, and you have to specify the grant ID when you make a Get all Messages request. Users aren't expected to have a large number of individual calendars, so the search options that Nylas offers for calendars are minimal.

If you know that the calendar you want to work with is the user's primary calendar (for providers that support it), you can use the word primary as the calendar locator instead of searching through the user's calendars to find a calendar ID.

Nylas allows you to add metadata to a set of reserved keys (key1, key2, key3, key4, and key5) on calendars, including virtual calendars.

You can search for metadata using the metadata_pair query parameter. For example, the following request returns all calendars where key1 is personal.

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars?metadata_pair=key1:personal' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

You can't create a query string that contains both a provider filter and a metadata filter, with the exception of calendar_id. For example, ?metadata_pair=key1:plan-party&title=Birthday returns an error.

Search for events

⚠️ You can only search for events from one specified calendar at a time. You must include a calendar ID or the word primary (for providers that support it) in your Get all Events request to search for events. Nylas returns a 400 error if you don't include a locator.

Nylas supports the following standard query parameters for Get all Events requests:

  • title, description, location
  • start, end
  • event_type - Supported for Google only.
  • updated_before, updated_after - Supported for Google, Microsoft, and EWS only.
  • ical_uid, master_event_id, busy - Not supported for iCloud.
  • attendees - Not supported for virtual calendars.
  • show_cancelled - Not supported for iCloud or EWS.

You can add metadata to a set of reserved keys (key1, key2, key3, key4, and key5) on events, then search for that metadata using the metadata_pair query parameter. For example, the following request returns all events where key1 is in-office.

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID>&metadata_pair=key1:in-office' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

You can't create a query string that contains both a provider filter and a metadata filter, with the exception of calendar_id. For example, ?calendar_id=<CALENDAR_ID>&metadata_pair=key1:plan-party&title=Birthday returns an error.

Microsoft Graph query considerations for events

When you search for events on Microsoft Graph grants, the number of days between the start and end times can't be greater than 1,825 days. If you need to find events over a longer time period, you'll need to make multiple requests.

iCloud query considerations for events

If you're searching for an event within a certain time range on an iCloud account, the difference between start and end can't be greater than six months. If you include a time range greater than six months, Nylas returns an "Invalid request" error similar to the following example.

"error": {
  "type": "invalid_request_error",
  "message": "The maximum time range for iCloud event queries is 6 months."
}

Search for drafts

Nylas supports the following standard query parameters for Get all Drafts requests:

  • subject, thread_id
  • any_email, to, cc, bcc
  • starred, has_attachment

Search for messages

Nylas supports the following standard query parameters for Get all Messages requests:

  • subject, thread_id
  • any_email, to, from, cc, bcc
  • received_before, received_after
  • in, unread, starred, has_attachment
  • fields

⚠️ Nylas doesn't support filtering for folders using keywords or attributes (for example, in:inbox returns a 400 error). Instead, you should use the folder ID with in to get the data you need.

You can also use the search_query_native parameter to define provider-specific query strings for Google, Microsoft Graph, EWS, and IMAP accounts. The query string must be URL-encoded.

Search for threads

Nylas supports the following standard query parameters for Get all Threads requests:

  • subject
  • any_email, to, from, cc, bcc
  • latest_message_before, latest_message_after
  • in, unread, starred, has_attachment

⚠️ Nylas doesn't support filtering for folders using keywords or attributes (for example, in:inbox returns a 400 error). Instead, you should use the folder ID with in to get the data you need.

You can also use the search_query_native parameter to define provider-specific query strings for Google, Microsoft Graph, EWS, and IMAP accounts. The query string must be URL-encoded.

Search messages and threads using search_query_native

You can include the search_query_native query parameter in the Get all Messages and Get all Threads requests. You can use it to search Google, Microsoft Graph, EWS, and IMAP accounts using a URL-encoded provider-specific query string.

⚠️ Some IMAP providers do not support the SEARCH operator, which results in a 400 Bad Request error. In such cases, you should use the standard query parameters for messages and threads to retrieve the data you need.

For example, if you want to search a Google account for messages with "foo" or "bar" in the subject, you first create the provider-specific query string (subject:foo OR subject:bar), then URL-encode it (subject%3Afoo%20OR%20subject%3Abar).

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?search_query_native=subject%3Afoo%20OR%20subject%3Abar" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

You can also use Microsoft Graph $filter queries in the search_query_native parameter. For example, if you want to find messages where one of the participants is j.doe@example.com, first create the query string ($filter=from/emailAddress/address eq 'j.doe@example.com'), then URL-encode it (%24filter%3Dfrom%2FemailAddress%2Faddress%20eq%20%27someuser%40example.com%27).

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages?search_query_native=%24filter%3Dfrom%2FemailAddress%2Faddress%20eq%20%27someuser%40example.com%27" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

If you include search_query_native in a Get all Messages request, you can only use a limited set of query parameters with it, depending on the provider:

  • Microsoft: in, limit, and page_token
  • Google: in, thread_id, limit, and page_token
  • EWS: All query parameters except thread_id

Similarly, you can only use the in, limit, and page_token parameters with search_query_native in a Get all Threads request on all providers except EWS. If you include any other query parameters, Nylas returns an error.

Search for folders

Nylas supports the parent_id query parameter for folders in Microsoft and EWS accounts only. You can use it to get all of the sub-folders under a specific folder.

Nylas doesn't support using keywords or attributes to reference folders on the provider (for example, in:inbox returns a 400 error). Instead, you should use specific folder IDs in your requests to get the data you need:

  1. Make a Get all Folders request.
  2. Inspect the folders Nylas returns, find the one you want to work with, and get its id.
  3. Use the id in your requests to work with the specified folder.

Search for attachments

You can search for attachments by making either a Get all Messages or Get all Threads request that includes the has_attachment query parameter. Nylas returns only the objects that include attachments, so you can sort through the objects to find the file you want to work with, then make a Get Attachment Metadata or Download Attachment request using the attachment ID and the associated message ID.

Search for contacts

Nylas supports the following standard query parameters for Get all Contacts requests:

  • email, source
  • phone_number - Supported for Google only.
  • group - Not supported for EWS.
  • recurse - Supported for Microsoft only.

Search for contact groups

You can search for contact groups on all providers except EWS. The Get all Contact Groups endpoint only accepts the query parameters that allow you to sort responses, and those that limit the results Nylas returns.

Microsoft Graph immutable identifiers

Generally, Nylas returns globally unique, immutable identifiers for messages and threads. This means that if you store a Nylas message_id or thread_id in your database, you can use it to get the same email message or thread at any time in the future. In some cases with Microsoft Graph, however, Nylas can't guarantee that the identifiers are immutable.

You might encounter this when using the following query parameters:

  • search_query_native
  • subject
  • to, cc, bcc, any_email

Microsoft Graph mutually exclusive query parameters

When you list messages or threads for Microsoft Graph accounts, certain types of query parameters become mutually exclusive. This means that if you use any parameters from the first group, you cannot use any from the second, and vice versa.

  • Group 1: Specific, broadly defined provider categories (thread_id, unread, and starred).
  • Group 2: Specific envelope fields (subject, to, cc, bcc, and any_email).

For example, you can't use the starred query parameter while also filtering for threads to a specific email address.

Historically, Nylas hasn't seen many combinations of these query parameters. If this limitation is negatively impacting your experience, contact Nylas Support.

EWS query considerations

Nylas query parameters can only work for on-premises Microsoft Exchange servers if an administrator has enabled search indexing for all mailboxes, and the Advanced Query Syntax (AQS) parser is supported. If query parameters are not returning expected results, contact the server administrator to check if this setting has been enabled.

Even though Nylas accepts any Unix timestamp for received_before, received_after, latest_message_before, and latest_message_after, the filtering on EWS is limited to the same day (for example, 01/01/2001), and the results are inclusive of the specified day. For more information, see Microsoft's notes on AQS query strings.

The accuracy of search results using to, from, cc, bcc, or any_email depends on the search indexing speed of your on-premises Microsoft Exchange server. For example, if you try to query Nylas for a message that just came in, but the Exchange server hasn't indexed it yet, Nylas doesn't return it. However, the message will be available after the next search index refresh.

IMAP query considerations

While Nylas does support the search_query_native parameter for IMAP accounts, not all IMAP servers support the standard IMAP SEARCH operators. If you send an unsupported SEARCH operator to an IMAP server, Nylas returns an error. When this happens, Nylas suggests using standard query parameters instead to get the data you need.