v3 Nylas Email and Calendar APIs

Number of APIs: 42

This API reference covers the Nylas Email and Calendar APIs.
See the see the Administration API documentation for information about working with Nylas applications, authentication, connectors, and webhook subscriptions.

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.

Pagination

Some queries result in multiple pages of data. Nylas includes a next_cursor response body field when there are more pages of results. To get the next page, pass the value of this header as the page_token query parameter on your next request.

You can use the limit query parameter to specify the maximum number of results you want in the page. A page might have less than limit results, but that doesn't mean that it's the last page. Use the presences of the next_cursor response body field to determine if there are additional pages.

Query Parameter	Type	Description
`limit`	integer	The number of objects to return. This defaults to 50 and has a maximum of 200.
`page_token`	string	An identifier that specifies which page of data to return. This value should be taken from the `next_cursor` response body field.

/me/ syntax for API calls

The Nylas API v3 Beta includes new /me/ syntax that 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 associated with the token 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.

For more information, see the API v3 Beta features and changes documentation.

Metadata

You can add key-value pairs to certain objects to store data against them. You can currently create, read, update, and delete metadata on Calendars and Events. Metadata is coming soon for message drafts and messages.

The metadata object is made of a list of key-value pairs. Keys and values can be any string.

Nylas also reserves five specific keys that you can include in the JSON payload of a query to filter the returned objects.

Metadata keys and filtering

Nylas reserves five metadata keys (key1, key2, key3, key4, key5) and indexes their contents. If you add metadata values to these keys, you can then add a metadata filter to a query so that only items with matching metadata are returned. You can also add these filters as URI parameters to a query, as in the examples below.

https://api.nylas.com/calendar?metadata_pair=key1:value
https://api.nylas.com/events?calendar_id=CALENDAR_ID&metadata_pair=key1:value

You cannot create a query that contains both a provider and metadata filter. Filters like the example below return an error message.

https://api.nylas.com/calendar?metadata_pair=key1:value&title=Birthday"

You do not need to include an event_id when filtering with metadata_filters.
What's this about? It seems a random

Example: Add metadata

The following example cURL request adds metadata to a Calendar. You can add metadata to Calendars and Events using a POST request with a --data-raw object for both.

In the example below, we add key1, which is one of the Nylas-indexed keys that you can use for filtering.

curl --location --request POST 'https://api.us.nylas.com/v3/grants/me/calendars' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name" : "Name of a calendar with metadata",
    "metadata":{
        "key1": "value to filter on"
    }
}'

The /me/ syntax in this example looks up the Grant associated with the request's access token, and uses the grant_id associated with the token 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.

Example: Query metadata

You can query the metadata you added by including a JSON object like the example below to a query that would return metadata-enabled objects. At this time calendars and events support metadata.

"metadata": {
    "key1": "value"
}

Example: Update and delete metadata

The example cURL command below creates a new Calendar that includes metadata.

curl --location --request POST 'https://api.us.nylas.com/v3/grants/me/calendars' \
--data-raw '{
    "metadata": {
        "key1": "Initial metadata value"
    }
}'

The example below updates the calendar metadata using a PUT command.

Note: The PUT command overwrites the entire metadata object. (The PATCH command behaves in the same way, and overwrites the entire metadata object.)

curl --location --request PUT &#x27;https://api.us.nylas.com/v3/grants/me/calendars/<CALENDAR_ID>&#x27; \
--data-raw '{
    "metadata": {
        "key1": "This key has been updated",
        "key2": "Added this new key"
    }
}'

The response will be similar to the following example.
Is this Nylas' response confirming the change? Or is this the response if you query for that metadata later?

"metadata": {
    "key1": "This key has been updated",
    "key2": "Added this new key"
}

If you update the above example with the PUT call below that does not include both metadata keys, Nylas deletes key2 from the metadata object.

curl --location --request PUT &#x27;https://api.us.nylas.com/v3/grants/me/calendars/<CALENDAR_ID>&#x27; \
--data-raw '{
    "metadata": {
        "key1": "New Value"
    }
}'

The response will then be similar to the example below.
Same question re: what kind of response.

"metadata": {
    "key1": "New Value"
}

v3-grants/{grant_id}-events-{event_id} - Return an Event GET {{baseUrl}}/v3/grants/:grant_id/events/:event_id?calendar_id=<string>
v3-grants/{grant_id}-calendars-{calendar_id} - Return a Calendar GET {{baseUrl}}/v3/grants/{{grant_id}}/calendars/{{calendar_id}}
v3-grants/{grant_id}-calendars-{calendar_id} - Delete a Calendar DELETE {{baseUrl}}/v3/grants/:grant_id/calendars/:calendar_id
v3-grants/{grant_id}-calendars - Create a Calendar POST {{baseUrl}}/v3/grants/:grant_id/calendars
v3-grants/{grant_id}-events-{event_id} - Update an Event PUT {{baseUrl}}/v3/grants/:grant_id/events/:event_id?notify_participants=true&calendar_id={{calendar_id}}
v3-grants/{grant_id}-messages-{message_id} - Return a Message GET {{baseUrl}}/v3/grants/:grant_id/messages/:message_id?fields=standard
v3-grants/{grant_id}-messages-{message_id} - Update a Message PUT {{baseUrl}}/v3/grants/:grant_id/messages/:message_id
v3-grants/{grant_id}-messages-schedules-{scheduleId} - Stop a Scheduled Message DELETE {{baseUrl}}/v3/grants/:grant_id/messages/schedules/:scheduleId
v3-grants/{grant_id}-messages-schedules - Retrieve Your Scheduled Messages GET {{baseUrl}}/v3/grants/:grant_id/messages/schedules
v3-grants/{grant_id}-messages - Return all Messages GET {{baseUrl}}/v3/grants/:grant_id/messages?limit=50