Skip to content
Docs
or

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.

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

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

You can query for specific metadata by including the metadata object in your request, or by using the metadata query parameters. Nylas doesn’t guarantee that metadata attached to an object will be returned in a specific order, so be sure to build your parsing methods with an arbitrary order in mind.

Metadata in v3 webhooks

If an object has metadata, Nylas includes the metadata property in *.created and *.updated webhook notifications, similar to the following example.

{
  "specversion": "1.0",
  "type": "event.updated",
  "source": "/google/events/realtime",
  "id": "<WEBHOOK_ID>",
  "time": 1732575192,
  "webhook_delivery_attempt": 1,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "object": {
      "busy": true,
      "calendar_id": "<CALENDAR_ID>",
      "created_at": 1732573232,
      "description": "Weekly one-on-one.",
      "grant_id": "<NYLAS_GRANT_ID>",
      "hide_participants": false,
      "html_link": "<LINK_TO_EVENT>",
      "ical_uid": "<ICAL_UID>",
      "id": "<EVENT_ID>",
      "location": "Room 103",
      "metadata": {
        "key1": "all-meetings",
        "key2": "on-site"
      },
      "object": "event",
      "organizer": {
        "email": "[email protected]",
        "name": "Nyla"
      },
      "participants": [{
        "email": "[email protected]",
        "name": "Leyah Miller",
        "status": "noreply"
      }],
      "read_only": false,
      "reminders": {
        "use_default": true
      },
      "status": "confirmed",
      "title": "One-on-one",
      "updated_at": 1732575179,
      "visibility": "public",
      "when": {
        "end_time": 1732811400,
        "end_timezone": "EST5EDT",
        "object": "timespan",
        "start_time": 1732809600,
        "start_timezone": "EST5EDT"
      }
    }
  }
}

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 Schedule recurring events documentation.