If you've got a non-trivial number of subscribers or emails, you'll almost certainly need to filter through them at some point — maybe it's to pull out all the subscribers who signed up in the last week, or to find all the emails that were sent to a specific audience.
Buttondown adheres to fairly strict REST principles, which means that filtering is done through query parameters.
The simplest way to filter is by a single field. For example, if you want to find all emails that have a status of "draft", you can do so by adding a status query parameter to your request:
If you want to filter by multiple fields, you can do so by adding multiple query parameters. For example, if you want to find all emails that have a status of "draft" and a source of "api", you can do so by adding both status and source query parameters to your request:
If you want to filter by multiple values on a single field, you can do so by adding the same query parameter multiple times. For example, if you want to find all emails that have a status of "draft" or "scheduled", you can do so by adding the status query parameter twice:
If you want to filter by values that are not in a given list, you can do so by prefixing the query parameter with a -. For example, if you want to find all emails that are not "draft", you can do so by adding a -status query parameter:
This is not supported for all endpoints; be sure to check the documentation for the endpoint you're interested in to confirm that it supports negative filtering.
OpenAPI's spec cannot actually surface this, but some specific endpoints in Buttondown's API allow you to filter by complex fields. For example, the subscriber list endpoint allows you to filter by metadata, which is a JSON field that can contain arbitrary data.
To filter by metadata, you can use the following query parameter:
The above query would return all subscribers where metadata contains the key foo with the value bar.
You can also filter by -metadata, which will return all subscribers where metadata does not contain the key foo:
And you can also filter by -metadata with a null value:
As of right now, this behavior only exists in the /v1/subscribers endpoint, but support for filtering by metadata will be added to other endpoints in the future.
Please note that the fields on which you can filter in a given endpoint vary, and you'll want to consult the individual endpoint's documentation to see what fields are available for filtering. For instance: