Add custom metadata to Nylas objects for filtering

You're sending a message from your app, and you need to remember which campaign it belonged to, or tie a calendar event back to the order in your own database. The obvious approach is a separate table mapping Nylas IDs to your records, which means a join on every read and a sync to keep current. There's a lighter way: attach your own data directly to the object as metadata, then filter objects by it later. Your campaign ID rides along on the message, and a single query pulls back every message in that campaign. This post covers tagging objects with the API and the CLI.

It's a worked use case rather than an endpoint tour, covering for setting and reading it from the terminal. I work on the CLI, so the commands below are the ones I reach for when I want to tag a send and find it again.

What metadata is and where it lives

Metadata is a field of your own key-value pairs that you attach to a Nylas object, and it's supported on messages, drafts, events, and calendars. The values are strings, you can store up to 50 pairs on a single object, and each value can hold up to 500 characters. That's room for a campaign slug, an external record ID, a workflow status, and whatever else ties the object back to your application, all carried on the object itself rather than in a side table.

The point of metadata is to avoid that side table. Instead of mapping a Nylas message ID to a row in your database and joining on every read, you put your application's data on the message and read it straight back. The object becomes self-describing from your app's point of view, so the campaign a message belongs to or the order an event is for travels with the object through every API call that returns it. For application data that's small and that you want to filter by, this is simpler than maintaining a parallel store.

The five-key rule that decides your schema

This is the single most important thing to understand about metadata, and missing it leads to a tagging scheme that can't be queried. You can store up to 50 key-value pairs, but only five keys, literally named key1 through key5, are indexed and filterable. Any other key you set is stored and returned with the object, but you cannot filter on it. So the keys you plan to query by have to live in key1 through key5.

This shapes how you design your tags. The values you'll search for, the campaign ID, the workflow status, the tenant, go in the five indexed keys, and you decide that mapping up front: key1 is the campaign, key2 is the run, and so on. Everything else, data you want to carry but never filter by, can use descriptive key names and ride along as the other 45 pairs. Get this backwards, putting a filterable concept in a free-form key, and you'll have stored the data but built no way to query it, which usually surfaces later when the filter you need silently returns nothing.

Set metadata when you send

You attach metadata at creation time by adding a metadata object to the request. On a — the metadata field and metadata_pair filter