{ "info": { "_postman_id": "f163c1ae-a8c5-4673-bfaa-ff30905d9351", "name": "v3 Nylas Email and Calendar APIs", "description": "This API reference covers the **Nylas Email and Calendar APIs**. \nSee the see the [Administration API documentation](https:///docs/api/v3-beta/admin/) for information about working with Nylas applications, authentication, connectors, and webhook subscriptions.\n\nThe Nylas API is designed using the [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) ideology to provide simple and predictable URIs to access and modify objects. Requests support [standard HTTP methods](http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) like GET, PUT, POST, and DELETE and [standard status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise.\n\n# Pagination\n\nSome 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.\n\nYou 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.\n\n| Query Parameter | Type | Description |\n| --- | --- | --- |\n| `limit` | integer | The number of objects to return. This defaults to 50 and has a maximum of 200. |\n| `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. |\n\n# /me/ syntax for API calls\n\nThe 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`).\n\nThe `/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.\n\nFor more information, see the [API v3 Beta features and changes documentation](https:///docs/v3-beta/features-and-changes/#changing-account_id-to-grant_id).\n\n# Metadata\n\nYou 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.\n\nThe `metadata` object is made of a list of key-value pairs. Keys and values can be any string.\n\nNylas also reserves five specific keys that you can include in the JSON payload of a query to filter the returned objects.\n\n## Metadata keys and filtering\n\nNylas 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.\n\n- `https://api.nylas.com/calendar?metadata_pair=key1:value`\n- `https://api.nylas.com/events?calendar_id=CALENDAR_ID&metadata_pair=key1:value`\n \n\nYou cannot create a query that contains **both** a provider and metadata filter. Filters like the example below return an error message.\n\n- `https://api.nylas.com/calendar?metadata_pair=key1:value&title=Birthday`\"\n \n\nYou do not need to include an `event_id` when filtering with `metadata_filters`. \nWhat's this about? It seems a random\n\n## Example: Add metadata\n\nThe 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.\n\nIn the example below, we add `key1`, which is one of the Nylas-indexed keys that you can use for filtering.\n\n``` bash\ncurl --location --request POST 'https://api.us.nylas.com/v3/grants/me/calendars' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"name\" : \"Name of a calendar with metadata\",\n \"metadata\":{\n \"key1\": \"value to filter on\"\n }\n}'\n\n ```\n\nThe `/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.\n\n## Example: Query metadata\n\nYou 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.\n\n``` json\n\"metadata\": {\n \"key1\": \"value\"\n}\n\n ```\n\n### Example: Update and delete metadata\n\nThe example cURL command below creates a new Calendar that includes metadata.\n\n``` bash\ncurl --location --request POST 'https://api.us.nylas.com/v3/grants/me/calendars' \\\n--data-raw '{\n \"metadata\": {\n \"key1\": \"Initial metadata value\"\n }\n}'\n\n ```\n\nThe example below updates the calendar `metadata` using a `PUT` command.\n\n**Note**: The `PUT` command overwrites the entire `metadata` object. (The `PATCH` command behaves in the same way, and overwrites the entire `metadata` object.)\n\n``` bash\ncurl --location --request PUT 'https://api.us.nylas.com/v3/grants/me/calendars/' \\\n--data-raw '{\n \"metadata\": {\n \"key1\": \"This key has been updated\",\n \"key2\": \"Added this new key\"\n }\n}'\n\n ```\n\nThe `/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.\n\nThe response will be similar to the following example. \nIs this Nylas' response confirming the change? Or is this the response if you query for that metadata later?\n\n``` json\n\"metadata\": {\n \"key1\": \"This key has been updated\",\n \"key2\": \"Added this new key\"\n}\n\n ```\n\nIf you update the above example with the `PUT` call below that does _not_ include both metadata keys, Nylas deletes `key2` from the `metadata` object.\n\n``` bash\ncurl --location --request PUT 'https://api.us.nylas.com/v3/grants/me/calendars/' \\\n--data-raw '{\n \"metadata\": {\n \"key1\": \"New Value\"\n }\n}'\n\n ```\n\nThe response will then be similar to the example below. \nSame question re: what kind of response.\n\n``` json\n\"metadata\": {\n \"key1\": \"New Value\"\n}\n\n ```", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "33173500", "_collection_link": "https://dark-crater-2051.postman.co/workspace/Linktastic~8f87da45-c044-4376-8f85-f103498cc06b/collection/33173500-f163c1ae-a8c5-4673-bfaa-ff30905d9351?action=share&source=collection_link&creator=33173500" }, "item": [ { "name": "v3", "item": [ { "name": "grants/{grant_id}", "item": [ { "name": "calendars", "item": [ { "name": "{calendar_id}", "item": [ { "name": "Return a Calendar", "request": { "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{bearerToken}}", "type": "string" } ] }, "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v3/grants/{{grant_id}}/calendars/{{calendar_id}}", "host": [ "{{baseUrl}}" ], "path": [ "v3", "grants", "{{grant_id}}", "calendars", "{{calendar_id}}" ] }, "description": "Returns a calendar by ID." }, "response": [ { "name": "Calendar Response", "originalRequest": { "method": "GET", "header": [ { "description": "Added as a part of security scheme: bearer", "key": "Authorization", "value": "Bearer " }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v3/grants/:grant_id/calendars/:calendar_id", "host": [ "{{baseUrl}}" ], "path": [ "v3", "grants", ":grant_id", "calendars", ":calendar_id" ], "variable": [ { "key": "grant_id", "value": "", "description": "(Required) ID of the grant to act upon. Use \"me\" to refer to the grant associated with an access token." }, { "key": "calendar_id", "value": "", "description": "(Required) ID of the calendar to act upon. Use \"primary\" to refer to the primary calendar associated with grant." } ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"request_id\": \"\",\n \"data\": \"