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 (for example, use the NOT operator).

Reduce response size with field selection

You can use the select query parameter in your requests to specify which fields you want to include in Nylas' response. This reduces response sizes, improves latency, and helps you avoid rate limiting issues and 429 errors. You can also use field selection in cases where you want to avoid working with user information that you think might be sensitive.

Field selection evaluates top-level object fields only. You can't use it to return only nested fields.

You can include the select query parameter with 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.
  • Webhooks. This is work in progress.

📝 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 --request GET \
  --url '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.