Metadata
You can add key-value pairs to certain objects to store data against them.
Create, read, update, and delete metadata on the following objects:
- Events
- Existing events
- New events
- Recurring calendar events
- Calendar
- New and existing calendars
- Messages
- Creating and updating messages
- Send
- Sending a message directly
- Drafts
- Creating and updating drafts
Metadata Object
The metadata object is made of a list of key-value pairs.
- Keys - A key can be any string. You are allowed up to 40 characters per key.
- Value - A value can be any string. You are allowed up to 500 characters per value.
In total, you can 50 key-value pairs per object. You cannot nest metadata objects.
...
"metadata":{
"hi": "6",
"event-type" : "party"
}
Adding Metadata
The following example creates a new calendar and adds the "event-type": "gathering"
key/value pair to the metadata
object. Metadata works the same across events and calendars.
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"
}
}'
Delete Metadata
You can overwrite the value of a key by passing in an empty string. Key-value pairs on events can only be removed through PUT
requests that omit that key-value pair.
Update an existing event with a PUT
request.
"metadata":{
"internal_event_id": ""
}
Key-Value Limit
Since the key with an empty string value persists, it will still count against your limit of 50 key-value pairs.
Query Metadata
You can query your added metadata. Using the following metadata object as an example:
"metadata": {
"goodmorning": "goodnight",
"green": "sour-apple",
"hello": "goodbye"
},
To query for keys, use:
https://api.nylas.com/events?metadata_key=goodmorning
https://api.nylas.com/calendar?metadata_key=green
To query for values, use:
https://api.nylas.com/calendar?metadata_value=goodnight
https://api.nylas.com/events?metadata_value=sour-apple
To query for multiple keys and values use:
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 with metadata:
https://api.nylas.com/calendar?metadata_search=any
To return all keys that match hello
and welcome
:
https://api.nylas.com/calendar?metadata_search=all&metadata_key=hello&metadata_key=welcome
To return values that do not match goodnight:
https://api.nylas.com/events?metadata_search=none&metadata_value=goodnight
You can combine the filters for targeted searching.
No match
If there is no match, the API returns a 200 OK with []
as a result.
Recurring Events
Recurring events are made of a primary event, with child events or the recurrence attached.
- You can add metadata to the primary event.
- Metadata is not attached to child events.
- The filter
expand_recurring=true
does not work with recurring events that have metadata. - If you change an event from non-recurring to recurring, any metadata on the non-recurring event is lost.
Keep in Mind
- Number of key-value pairs per object: 50
- Number of characters per key: 40
- Number of characters in the value: 500
- Not able to nest metadata objects
- Webhooks are not supported when event metadata is updated. When an event is created an
event.created
webhook will fire.