Using metadata in Nylas

Event metadata is included with all Nylas plans. Also available for Sandbox applications.

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. Keys and values must be strings, and you can store up to 50 key-value pairs on an object. A non-string value returns a 400 error. 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. Threads, grants, and Notetaker bots don’t have a metadata object.

Agent Account grants support metadata on Events, Messages, and Drafts. The limits, reserved keys, and metadata_pair filtering on this page all apply. See Supported endpoints for Agent Accounts for the per-object detail.

Reserved metadata keys

Nylas reserves five metadata keys (key1, key2, key3, key4, and key5) and indexes their contents. In availability requests, Nylas uses key5 to identify events that count towards the round-robin calculation. Scheduler also sets key5 to the Configuration ID on the events it books. See Metadata that Scheduler adds to events.

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/v3/grants/<NYLAS_GRANT_ID>/calendars?metadata_pair=key1:on-site
• https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/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

You can’t combine metadata_pair with provider filters. For example, https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars?metadata_pair=key1:plan-party&title=Birthday returns 400 Query params can only filter by either `metadata` or `provider filters`. Event and Calendar queries accept calendar_id, start, end, and pagination parameters alongside metadata_pair. Message and Draft queries accept only pagination parameters, select, and fields.

Add metadata to objects

You can add metadata to both new and existing objects. The following example creates a Calendar with the key1 and key2 metadata keys.

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

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 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

Filter objects by metadata with the metadata_pair query parameter, in the format key:value. It works on Calendars, Events, Messages, Drafts, and Contacts, and matches one pair per request.

metadata_pair accepts only the reserved keys, key1 to key5. Any other key returns 400 metadata filtering not allowed on provided `key`, and an empty key or value returns metadata filtering requires a non-empty key and value. On Events, metadata_pair can’t be combined with expand_recurring.

Nylas doesn’t guarantee the order of keys in a returned metadata object, so don’t depend on key order when you parse it.

Metadata on drafts and sent messages

When you send a Draft that has metadata, the sent Message keeps the Draft’s metadata. Use this to tag a message while it’s a draft and filter the sent message by the same key later.

Metadata that Scheduler adds to events

Scheduler writes metadata to the events it creates for bookings, except for Group Configuration events. Don’t overwrite these keys when you update a Scheduler event, because PUT and PATCH replace the whole metadata object.

Key	Value
source	scheduler
key5	The Scheduler Configuration ID
scheduler_last_start	The start time Scheduler last set, as a Unix timestamp string
scheduler_last_end	The end time Scheduler last set, as a Unix timestamp string
scheduler_updated_at	When Scheduler last changed the event, as a Unix timestamp string

Scheduler Configurations don’t have a metadata object of their own. To store a value on every booking, add an additional field with type: "metadata" instead. That field isn’t a metadata object: it’s a hidden field on the booking form, and the scheduling page sends its value with each booking. See Store metadata on bookings.

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

*.created and *.updated webhook notifications for Events, Calendars, and Messages can include the object’s metadata, as in the following example. Don’t rely on it being there: a message.created notification can arrive without the message’s metadata, so fetch the object by ID if your handler depends on it. Tracking notifications, such as message.opened, carry the message’s tracking label, not its metadata.

Workflow templates can read event metadata and hidden Scheduler metadata fields from the same payloads.

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.
• Child events return the primary event’s metadata, with any keys set on the child event taking precedence.
• 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.
• A metadata_pair filter matches the metadata stored on each event, so a value set only on the primary event returns the primary event, not each child event.
• Changing an event from non-recurring to recurring can drop its metadata. Check the event after the change and write the metadata again if it’s missing.

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