Retrieve Email

Buttondown's filtering schema can be used for multiple things:

• Filtering the audience of an email to a specific subset
• Creating finely-tuned automations

Filters are fractal; they can be nested in groups, and groups can be nested in other groups. This is accomplished through a tree-like structure. Every "FilterGroup" has a "predicate" field, which is either "and" or "or", which determines how the filters and groups within the group are combined, a "groups" field, which is a list of "FilterGroup" objects (that's that recursive bit!), and a "filters" field, which are the leaf-level filters themselves.

Let's say you want a simple filter: all subscribers who have a tag whose ID is sub_tag_0j6hb7h40j6hb7h40j6hb7h40j. You can do that like this:

{
    "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40j"}],
    "groups": [],
    "predicate": "and"
}

Now, let's say you want to filter for subscribers who have that tag and a tag whose ID is sub_tag_0j6hb7h40j6hb7h40j6hb7h40k. You can do that like this:

{
    "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40j"}, {"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40k"}],
    "groups": [],
    "predicate": "and"
}

If you wanted to change that and to an or, you can do that like this:

{
    "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40j"}, {"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40k"}],
    "groups": [],
    "predicate": "or"
}

Now, let's say you want to filter for subscribers who have the first tag or both the second tag and a third tag whose ID is sub_tag_0j6hb7h40j6hb7h40j6hb7h40m. This is where the whole nested thing comes in handy. You can do that like this:

{
    "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40j"}],
    "groups": [
        {
            "filters": [{"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40k"}, {"field": "subscriber.tags", "operator": "contains", "value": "sub_tag_0j6hb7h40j6hb7h40j6hb7h40m"}],
            "groups": [],
            "predicate": "and"
        }
    ],
    "predicate": "or"
}

You can read more about the specific filter construction in the Filter documentation.