Using metadata in Nylas

Nylas lets you add key-value pairs to certain objects so you can store data against them.

What’s metadata?

You can use the metadata object to add custom key-value pairs to Calendars, Events, Messages, Drafts, and Contacts. Both keys and values can be strings, and you can store up to 50 key-value pairs on an object. Keys can be up to 40 characters long, and values can be up to 500 characters.

Contact metadata works for Google, Microsoft Graph, EWS, hosted IMAP, native iCloud, and native Yahoo grants. It belongs to Contact objects only. Contact Group schemas, list responses, and endpoints don’t support metadata.

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

Reserved metadata keys

Nylas reserves five metadata keys (key1, key2, key3, key4, and key5) and indexes their contents. Nylas uses key5 to identify events that count towards the max-fairness round-robin calculation for event availability.

You can add values to each of these reserved keys and reference them in a query to filter the objects that Nylas returns, 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
https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/contacts?metadata_pair=key1:customer-123

Add metadata to 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 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 /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID> 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 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.

Contact metadata behavior

Nylas owns Contact metadata and stores it separately from provider data. It’s never written into a provider Contact or CardDAV vCard. Create, get, list, and update responses hydrate the metadata field from Nylas storage.

Contact updates follow the shared replacement rule with one important omission behavior:

Omitting metadata preserves the current object.
Supplying a metadata object replaces the whole current object.
Supplying "metadata": {} clears it.
Sending only metadata updates Nylas storage without writing provider fields.
Deleting a Contact also cleans up its metadata.
Deleting the grant removes metadata stored for its Contacts.

Provider and metadata writes use different systems and aren’t atomic. If a request changes both and returns an error, fetch the Contact to reconcile current state before retrying. Native iCloud and Yahoo metadata uses the public Contact ID, which derives from the provider href. If a provider-side move changes that ID, Nylas treats the old and new IDs as different resources; persist the latest ID and write the desired metadata under it.

Contact metadata queries support limit and page_token. You can’t combine metadata_pair with email, phone_number, group, recurse, or a non-default source. When a metadata record points to a provider contact that no longer exists, Nylas removes the stale record while resolving the query.

See Add metadata to a contact for curl examples covering create, metadata-only update, filtering, clearing, and deletion cleanup.

Metadata in webhooks

For notification schemas that support metadata enrichment, Nylas includes the metadata property in *.created and *.updated webhook notifications, similar to the following example.

A Contact metadata-only update doesn’t create a provider-change notification. When a Contact notification drives metadata-sensitive work, make a Get Contact request to hydrate the current authoritative metadata before applying the change.

{
  "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 and child event.
Metadata added to the primary event is passed to the child events.
Metadata updates made to a child event are applied only to that specific child event and aren’t propagated to the primary or other instances in the series.
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.