Metadata

What is metadata?

This is a great question! The short answer is "structured key-value data". As of this writing, you can only apply metadata to subscribers, meaning that you can attach any sort of key-value pairs you'd like to your subscribers. This can be things like identifying information such as first and last names, so you can apply "mail merges" to your newsletter; or it could be for internal use only, such as customer IDs to tie subscribers back to your web application.

I'd recommend also reading up on Stripe's explanation of metadata — Buttondown's implementation and philosophy behind it is very similar.

What constitutes valid metadata?

Internally, metadata is stored as raw JSON, so you can be pretty liberal with what you place into it. (If you try and view or set metadata using the Buttondown interface, there will likely be some stringification issues — for complex use cases, it's recommended to use the API or an integration like Zapier.)

Note that while you can store metadata keys with hyphens (such as first-name), it is difficult to access that metadata when writing an email: {{ subscriber.metadata.first-name }} is a syntax error due to the templating language used by Buttondown. As a result, I recommend using underscores instead (such as first_name).

Adding metadata

Interested in adding metadata to your subscribers? Learn more about doing so in the metadata section of building your subscriber base.

Searching for metadata

You can search for metadata in Buttondown by using the key:value notation. For instance, if you want to find all subscribers with a metadata key-value pair of {"first_name": "Alex"}, you type in first_name:Alex:

At the moment, this does not work with more than one key-value pair; location:seattle industry:finance will not do what you would like it to. (It will eventually, though!)

Programmatically using metadata.

Interested in setting metadata via the API? Check out the API documentation!