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.

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

Metadata can be nested — you can store objects and arrays within your metadata. For example:

{
  "first_name": "John",
  "address": {
    "street": "123 Main St",
    "city": "Seattle",
    "state": "WA"
  },
  "preferences": ["email", "sms"]
}

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

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

You can search for metadata in Buttondown by using the key:value notation:

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!)

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