Nylas API Reference

The Nylas API is designed using the REST ideology to provide simple and predictable URIs to access and modify objects. Requests support standard HTTP methods like GET, PUT, POST, and DELETE, and standard status codes. Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise.

You can use the Nylas Postman collection to quickly start using the Nylas APIs. For more information, check out the Nylas Postman collection documentation.

Enable compression to optimize performance

The Email, Calendar, Contacts, and Scheduler APIs return gzip-compressed responses when your request includes the Accept-Encoding: gzip header. Most HTTP libraries negotiate and decompress gzip responses automatically. With curl, use --compressed. Nylas skips compression for responses under about 200 bytes.

Compression pairs well with query parameters that limit the number of objects returned and field selection that limits which fields come back in each object. For the full walkthrough, including webhook, Pub/Sub, and SNS compression, see Reducing payload size with compression.

Query parameters

Nylas allows you to include query parameters in GET requests that return a list of results. Query parameters let you narrow the results Nylas returns, meaning fewer requests to the provider and less data for your application to sift through. For more information, see Rate limits in Nylas.

The table below shows the query parameters you can use for the GET requests in the Email, Calendar, Contacts, and Notetaker APIs.

You can use the limit parameter to set the maximum number of results Nylas returns for your request. Nylas recommends setting a lower limit if you encounter rate limits on the provider. For more information, see Avoiding rate limits in Nylas.

Nylas supports case-insensitive partial matches for some query parameters:

• description, location, and title in Get all Events requests.
• subject in Get all Messages, Get all Drafts, and Get all Threads requests.

If the specified field contains the query term, Nylas matches it regardless of the case. For example, if you set the subject query parameter to march in a Get all Messages request, Nylas might return the following messages:

• "Company March Meeting"
• "Today in history: Mussolini's march on Rome"
• "Your coupon code: mARch"

Since Nylas matches keywords, it won't return the following messages:

• "Confirmation code: abcMarch123"
• "McDonald's golden arches"

Pagination

Nylas might return multiple pages of data when you make a "Get all" request (for example, Get all Events). When this happens, Nylas includes the next_cursor field in its response. You can pass the value of next_cursor as the page_token query parameter in your next request to get the next page of results.

You can use the limit parameter to specify the maximum number of results you want in one page of data. If you see rate limits from the provider, try using a smaller limit value.

Updating objects

PUT and PATCH requests behave similarly in Nylas: when you make a request, Nylas replaces all data in the nested object with the information you define. Because of this, your request might fail if you don't include all mandatory fields.

Nylas doesn't erase the data from fields that you don't include in your request, so you can define only the mandatory fields and any that you want to update.

/me/ syntax for API calls

Nylas includes the /me/ syntax which you can use in access-token authorized API calls instead of specifying a user's grant ID (for example, GET /v3/grants/me/messages).

The /me/ syntax looks up the grant associated with the request's access token, and uses the grant_id as a locator. You can use this syntax for API requests that access account data only, and only if you use access tokens to authorize requests. You can't use this syntax if you're using API key authorization, because there is no grant associated with an API key.

Metadata

You can use the metadata object to add a list of key-value pairs to Calendar, Event, Message, and Draft objects so you can store custom data with them. Both keys and values can be any string. If you want to filter on metadata, however, you must write values to one of the five Nylas-specific keys.

For more information, see the Metadata documentation.

Metadata keys and filtering

Nylas reserves five metadata keys (key1, key2, key3, key4, key5) and indexes their contents. Nylas uses key5 to identify events that count towards the max-fairness round-robin calculation for event availability. For more information, see Group availability and booking best practices.

You can add values to each of these reserved keys, and reference them in a query to filter the objects that Nylas returns. You can also add these filters as query parameters, as in the following examples:

• https://api.us.nylas.com/calendar?metadata_pair=key1:on-site
• https://api.us.nylas.com/events?calendar_id=<CALENDAR_ID>&metadata_pair=key1:on-site

You can't create a query that includes both a provider and metadata filter, other than calendar_id. For example, https://api.us.nylas.com/calendar?metadata_pair=key1:plan-party&title=Birthday returns an error.

Reduce response size with field selection

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

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

• All DELETE endpoints.
• All Attachments endpoints.
• All Smart Compose endpoints.
• The Send Message endpoint.
• The Create a Draft endpoint.

Field selection helps to reduce the size of the 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 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.

For example, the following request specifies Nylas should return only the id and name fields of the Calendar object.

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/me/calendars?select=id,name'

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

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": [
    {
      "id": "5d3qmne77v32r8l4phyuksl2x",
      "name": "My Calendar"
    },
    {
      "id": "5d3qmne77v32r23aphyuksl2x",
      "name": "My Calendar 2"
    }
  ]
}

Nylas encoding

Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise.