Nylas lets you add key-value pairs to certain objects so you can store data against them.
What is metadata?
You can use the metadata object to add a list of custom key-value pairs to Calendars, Events, Messages, and Drafts. Both keys and values can be any string, 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.
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-sitehttps://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 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" } }'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
You can only query for the Nylas-specific metadata keys.
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 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": { "name": "Nyla" }, "participants": [{ "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 are not 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.