Only show these results:

Event Metadata

Event Metadata is in beta

While in a beta state, we can not guarantee its stability. We may make updates or breaking changes at any time.

Event Metadata lets you add key-value pairs to event objects.

Event Metadata Object

The event 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 50 characters per value.

In total, you can 50 key-value pairs per object. You can not nest metadata objects.

...
"metadata":{
"hi": "6",
"event-type" : "party"
}

You can add event metadata to:

  • Existing events
  • New events
  • Recurring calendar events

Add Event Metadata Object

Create an event by sending a POST request to /event. Add the metadata object to the request.

You can add multiple key-value pairs in one request.

curl --location --request POST 'https://api.nylas.com/events' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"title": "Birthday Party",
"location": "Roller Rink",
"calendar_id": "{calendar_id}",
"status": "confirmed",
"busy": true,
"read_only": false,
"participants": [
{
"name": "Thomas Edison",
"email": "tom@brightideas.com"
}
],
"description": "Let'\''s Party!!!",
"when": {
"start_time": "1615330800",
"end_time": "1615334400"
},
"metadata":{
"number_of_guests": "55",
"event_type": "birthday"
}
}'

Update Event Metadata

Event Metadata can be updated by making a PUT request to the event that has the metadata object and adding or updating the existing information.

curl --location --request PUT 'https://api.nylas.com/events' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"title": "Birthday Party",
"location": "Roller Rink",
"calendar_id": "{calendar_id}",
"status": "confirmed",
"busy": true,
"read_only": false,
"participants": [
{
"name": "Thomas Edison",
"email": "tom@brightideas.com"
}
],
"description": "Let'\''s Party!!!",
"when": {
"start_time": "1615330800",
"end_time": "1615334400"
},
"metadata":{
"number_of_guests": "55",
"event_type": "birthday",
"internal_event_id": "b55469dk"
}
}'

Delete Event Metadata

As of now, key-value pairs on events can not be deleted. You can overwrite the value of a key by passing in an empty string.

Send a PUT request to an existing event.

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

Event Metadata Response Example

{
"account_id": "{account_id}",
"busy": true,
"calendar_id": "{calendar_id}",
"description": "Let's Party!!!",
"ical_uid": null,
"id": "6ndts0aut32bzrfd9dmzma1fr",
"job_status_id": "{job_status_id}",
"location": "Roller Rink",
"message_id": null,
"metadata": {
"event_type": "birthday",
"internal_event_id": "b55469dk",
"number_of_guests": 55
},
"object": "event",
"owner": "Albert Einstein <al@particletech.com>",
"participants": [
{
"comment": null,
"email": "tom@brightideas.com",
"name": "Thomas Edison",
"status": "noreply"
}
],
"read_only": false,
"status": "confirmed",
"title": "Birthday Party",
"when": {
"end_time": 1615334400,
"object": "timespan",
"start_time": 1615330800
}
}

Query Event Metadata

You can query events using the metadata key and value. 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/events?metadata_key=green
  • https://api.nylas.com/events?metadata_key=hello

To query for values, use:

  • https://api.nylas.com/events?metadata_value=goodnight
  • https://api.nylas.com/events?metadata_value=sour-apple
  • https://api.nylas.com/events?metadata_value=goodbye

The response will return the event objects matching those keys.

If there is no match, we return an empty response with a 200 OK.

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.