Only show these results:

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
  • Accounts
    • New and existing accounts
  • 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

For this example, we'll use accounts. Metadata works the same across events, calendars, and accounts.

curl --location --request PUT 'https://api.nylas.com/a/<NYLAS_CLIENT_ID>/accounts/<ACCOUNT_ID>' \
-u "<CLIENT_SECRET>:"
--header 'Content-Type: application/json' \
--data-raw '{
"metadata":{
"hello": "goodbye"
}
}'

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
  • https://api.nylas.com/a/{client_id}/accounts/{id}?metadata_key=hello

To query for values, use:

  • https://api.nylas.com/calendar?metadata_value=goodnight
  • https://api.nylas.com/events?metadata_value=sour-apple
  • https://api.nylas.com/a/{client_id}/accounts/{id}?metadata_value=goodbye

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&hello:goodbye
  • https://api.nylas.com/a/{client_id}/accounts/{id}?metdata_key=goodmorning&metadata_value=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/a/{client_id}/accounts/{id}?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.