Version:
Only show these results:

Metadata

Nylas lets you add key-value pairs to certain objects so you can store data against them. This page explains how you can use metadata in Nylas v3 and v2.

ℹ️ Event, message, and account metadata is available for Free, Core, and Plus plans. Available for demo purposes in the Free-tier Sandbox. Not available for Calendar-only plans.

What is 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, and you can store up to 50 key-value pairs per object. Keys can be up to 40 characters long, and values can be up to 500 characters.

...
  "metadata": {
    "example-key": "This is an example.",
    "key1" : "Sample"
  },
...

Nylas doesn't support nested metadata objects, and doesn't generate notifications when you update the metadata object.

Metadata in Nylas v3

You can create, read, update, and delete metadata on the following v3 objects:

Nylas metadata keys

Nylas v3 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.

Add metadata to v3 objects

You can add metadata to both new and existing objects. The following example adds the "event-type": "meeting" key-value pair to an existing calendar.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/me/calendars' \
  --header 'Content-Type: application/json' \
  --data '{
    "name" : "Example metadata calendar",
    "metadata":
    {
      "key1": "all-meetings",
      "key2": "on-site"
    }
  }'

⚠️ Keep in mind: Both PUT and PATCH requests overwrite the entire metadata object. This means that if you update the calendar in the example above but include only key1, Nylas deletes key2.

Remove metadata from v3 objects

To remove a key-value pair from an object, make a PUT or PATCH request that includes the metadata you want to keep. As an example, consider the following metadata on an existing calendar:

...
  "metadata": {
    "key1": "all-meetings",
    "key2": "on-site"
  },
...

If you make the following PUT request, Nylas deletes key1 and keeps key2.

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/me/calendars/<CALENDAR_ID>' \
  --data '{
    "metadata":
    {
      "key2": "on-site"
    }
  }'

Query metadata on v3 objects

⚠️ In Nylas v3, you can only query for the Nylas-specific metadata keys. For more information, see Nylas metadata keys.

You can query for specific metadata by including the metadata object in your request, or by using the metadata query parameters.

Metadata in Nylas v2

You can create, read, update, and delete metadata on the following v2 objects:

Add metadata to v2 objects

💡 Tip: Metadata works the same across v2 calendars and events.

The following example creates a calendar and adds the "event-type": "gathering" key-value pair to the metadata object.

curl --request POST \
  --url https://api.nylas.com/calendars \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My New Calendar",
  "description": "Description of my new calendar",
  "location": "Location description",
  "timezone": "America/Los_Angeles",
  "metadata": {
    "event-type": "gathering"
  }
}'

Remove metadata from v2 objects

Although you can't fully remove a key-value pair from the metadata object, you can overwrite the value by passing an empty string, as in the following example.

curl --request PUT \
  --url https://api.nylas.com/calendars/<CALENDAR_ID> \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My New Calendar",
    "description": "Description of my new calendar",
    "location": "Location description",
    "timezone": "America/Los_Angeles",
    "metadata":
    {
      "internal_calendar_id": ""
    }
  }'

When you do this, the key-value pair still counts against Nylas' metadata limit. This is because the internal_calendar_id key still exists — its value is just empty.

You can only remove key-value pairs on events by making a PUT request that omits the pair.

Query metadata on v2 objects

After you add metadata to an object, you can query for it in your requests. As an example, consider the following metadata object:

...
  "metadata": {
    "goodmorning": "goodnight",
    "green": "sour-apple",
    "hello": "goodbye"
  },
...

To query for the keys, include the metadata_key parameter in your request.

  • https://api.nylas.com/events?metadata_key=goodmorning
  • https://api.nylas.com/calendar?metadata_key=green

Similarly, you can query for values using the metadata_value parameter.

  • https://api.nylas.com/calendar?metadata_value=goodnight
  • https://api.nylas.com/events?metadata_value=sour-apple

If you want to query for a specific key-value pair, include the metadata_pair parameter, and separate the key and value using a colon (:).

  • https://api.nylas.com/calendar?metadata_pair=goodmorning:goodnight
  • https://api.nylas.com/events?metadata_pair=goodmorning:goodnight&metadata_pair=hello:goodbye

To return any object that has metadata, use the metadata_search=any query parameter (for example, https://api.nylas.com/calendar?metadata_search=any).

If you want to return all keys that match hello or welcome, include the metadata_search=all and metadata_key parameters (for example, https://api.nylas.com/calendar?metadata_search=all&metadata_key=hello&metadata_key=welcome).

Finally, if you want to return values that don't match goodnight, include the metadata_search=none and metadata_value parameters (for example, https://api.nylas.com/events?metadata_search=none&metadata_value=goodnight).

💡 You can combine any of the above filtering syntax to create targeted searches. This helps to reduce the volume of data Nylas returns, and can improve performance.

If you query for specific metadata, but Nylas doesn't find a match, it returns a 200 OK response that contains [].

Metadata for recurring events

Recurring events are comprised of a primary ("main") event, with child events or the recurrence attached. When working with metadata on recurring events, keep the following things in mind:

  • You can add metadata to the primary event only.
  • Metadata added to the primary event isn't passed to the child events.
  • If you change an event from non-recurring to recurring, any metadata from the non-recurring event is lost.

For more information about recurring events, see the v3 Schedule recurring events and v2 Schedule recurring events documentation.