Metadata
Nylas allows you to 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 and Event 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 up to 500 characters.
...
"metadata": {
"example-key": "This is an example.",
"key1" : "Sample"
},
...
Nylas does not support nested metadata
objects.
Nylas does not 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:
đ Metadata support for Messages and Drafts is coming soon.
Nylas metadata keys
In v3, Nylas 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
â ī¸ Nylas ties metadata to the calendar ID you pass in your request, so if you set calendar_id
to primary
, you must specify primary
when querying for the metadata later. Similarly, if calendar_id
is set to an account's primary calendar ID, you must specify that ID when querying for the metadata.
You cannot create a query that contains 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 code sample 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 contains 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:
- New and existing Events, including recurring events.
- New and existing Calendars.
- New and existing Messages.
- Email messages using the Send API.
- New and existing Drafts.
Add metadata to v2 objects
đĄ Tip: Metadata works the same across v2 calendars and events.
The following code sample 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' \
--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 cannot 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' \
--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 contains 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 ("master") 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 is not 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.