Avoiding rate limits in Nylas

Your project needs to adhere to both Nylas- and provider-set rate limits. This page lays out some best practices that we recommend you implement to avoid being rate-limited.

What are rate limits?

Service providers set rate limits to 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 the Nylas APIs for information and Nylas queries the provider on your behalf. Sometimes, a single request to the Nylas APIs can require multiple requests to the provider to return the information you’re looking for. For example, a user might cause rate limits when they bulk-send messages to a group of recipients. In this case, your project makes a large number of Send Message requests, and Nylas makes its own requests to the provider.

When a user hits Nylas’ rate limits, Nylas temporarily stops responding to requests and instead returns a 429 error code.

Threads rate limits

The Return all Threads endpoint makes a significant number of calls to the provider for each request you make. We strongly recommend using query parameters to limit the data Nylas returns.

Because of the number of calls Nylas makes to the provider for each Get all Threads request, you might encounter rate limits when working with large threads of messages. You can take the following steps to avoid this:

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

Filter requests using query parameters

One of the best ways to avoid hitting rate limits is to use query parameters to filter the results Nylas returns. Nylas supports query parameters for each GET endpoint that returns a list of results.

• limit: Set the maximum number of results Nylas returns for your request.
• 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 messages or threads.
• select: Specify the fields Nylas returns for your request (for example, select=id,updated_at).

For more information, see the Administration and Email, Calendar, and Contacts API references.

Provider-native search strings for email filtering

You can search for messages using a Get all Messages request and the available query parameters. Similarly, you can search for threads by making a Get all Threads request.

The search_query_native query parameter lets you add provider-specific query strings to your request (for example, you can use it to filter with the NOT operator).

Reduce response size with field selection

You can use the select query parameter to specify which fields you want Nylas to return. 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.

For example, when working with potentially large objects like messages, you can have Nylas return only the fields you want to work with and skip the big ones like body. The following example specifies Nylas should return only the id, from, and subject fields of the Message object.

RequestResponse (JSON)

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/me/messages?select=id,from,subject' \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": [
    {
      "id": "<MESSAGE_ID>",
      "from": "[email protected]",
      "subject": "RE: Annual Philosophy Club Meeting"
    },
    {
      "id": "<MESSAGE_ID>",
      "from": "[email protected]",
      "subject": "Your order has been delivered!"
    }
  ]
}

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.

We strongly suggest you always use field selection so you only get the data that you need.