Version:
Only show these results:

Avoiding rate limits in Nylas

Your application must adhere to both Nylas- and provider-set rate limits. This page describes best practices that Nylas recommends you implement to avoid hitting rate limits.

What are rate limits?

Service providers set rate limits which cap the number of requests you can make for data over a set period of time. If the volume of requests meets or exceeds a rate limit, the provider temporarily reduces its response rate and returns an error.

When you integrate with Nylas, you make requests to Nylas for information, and Nylas queries the provider on your behalf. Sometimes, a single request to the Nylas API can require multiple requests to the provider to return the information. For example, an end user might cause rate limits when they bulk-send email messages to a group of recipients. In this situation, your project makes a large number of POST /v3/grants/<NYLAS_GRANT_ID>/messages/send requests to the Nylas API, and Nylas makes its own requests to the provider. If the number of requests meets or exceeds the provider's set limits, the provider returns an error and temporarily limits API requests.

When an end user hits Nylas' rate limits, Nylas temporarily stops responding to API requests and returns a 429 error code.

Filter results using query parameters

One of the best ways to prevent rate limit errors is to use query parameters to filter the results Nylas returns for API requests. Nylas offers query parameters for each GET request that returns a list of results.

You can also use the following parameters to limit the data Nylas returns for most GET requests that return a list of results:

  • limit: Set the maximum number of results Nylas returns.
  • offset: Set a zero-based offset from Nylas' default sorting (for example, offset=30 skips the first 30 results).
  • search_query_native: Specify a provider-specific query string to search email messages or threads. Available for Google, Microsoft Graph, and IMAP.
  • select: Specify the fields Nylas will return for your request (for example, select=id, updated_at).

For more information, see the Administration and Email, Calendar, and Contacts reference documentation.

Provider-native search strings for email filtering

You can search for email messages using a GET /v3/grants/<NYLAS_GRANT_ID>/messages request. This replaces the v2 GET /messages/search request. Similarly, GET /v3/grants/<NYLAS_GRANT_ID>/threads replaces the v2 GET /threads/search.

You can include the search_query_native parameter to add provider-specific search query strings to your criteria (for example, to use the NOT operator). The value that you specify for the native search string must be URL-encoded.

If you include the search_query_native parameter, you can only use a few specific query parameters with it.

  • For Microsoft and IMAP, you can only use in, limit and page_token.
  • For Google, you can use in, limit, page_token, and thread_id.
  • For EWS, you can use any query parameters except thread_id.

If you have Microsoft as a provider, you can also use Microsoft Graph $filter queries in the search_query_native string. Create your filter query, prefix it with $filter= then URL encode it. For example, the Graph filter query $filter=from/emailAddress/address eq 'j.doe@example.com' becomes %24filter%3Dfrom%2FemailAddress%2Faddress%20eq%20%27j.doe%40example.com%27.

Reduce response size with field selection

Field selection allows you to use the select query parameter to specify which fields you want to include in Nylas' response.

Field selection helps to reduce the size of Nylas' response, improves latency, and helps you avoid rate limiting issues. You can also use it in cases where you want to avoid working with information from your end users that you think might be sensitive.

Field selection can evaluate top-level object fields only. You cannot use it to return only nested fields.

You can use field selection for all Nylas API endpoints, except the following:

  • All DELETE endpoints.
  • All Attachments endpoints.
  • All Smart Compose endpoints.
  • All Webhooks endpoints.
  • The Send Message endpoint.
  • The Create a Draft endpoint.
📝 Note: Nylas strongly suggests you always use field selection, so you only get the data that you need.

Example - reducing message response size

For example, for objects like Messages that might be large, you could select just the fields you actually want, and skip the big ones like body. The following request specifies Nylas should return only the id, from and subjectfields of the Message object.

curl --location --request GET 'https://api.nylas.com/v3/grants/me/messages?select=id,from,subject'

The Nylas response payload includes only the id, from and subject fields in the data object, as in the example below.

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": [
    {
      "id": "5d3qmne77v32r8l4phyuksl2x",
      "from": "kris@example.com",
      "subject": "Re: Philosophy club meeting"
    },
    {
      "id": "5d3qmne77v32r23aphyuksl2x",
      "from": "nyla.global.express@example.com",
      "subject": "Your order has been delivered!"
    }
  ]
}

Threads rate limits

⚠️ The Return all threads endpoint makes a significant number of calls to the provider for each request you make. Because of this, Nylas strongly recommends using query parameters to limit the threads data you receive.

Because of the number of calls Nylas makes to the provider for each GET /v3/grants/<NYLAS_GRANT_ID>/threads request, you might encounter rate limits when working with large threads of email messages. You can take the following steps to avoid rate limits:

  • Specify a lower limit to reduce the number of results Nylas returns.
  • Add query parameters to your request to filter for specific information.