Nylas Email, Calendar, and Contacts APIs

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.

The Nylas APIs support application/gzip (compressed) format as well as the standard plaintext application/json. Using gzip compression greatly improves API performance, especially when you use it with query parameters to limit the objects returned and field selection to limit which fields you're querying for.

If you enable this, make sure your project watches the response headers so it can expand compressed responses when needed. You can read more about this in the Curl.dev documentation.

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, and Contacts 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"

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.

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.

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.

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.

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.

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"
    }
  ]
}

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