Itemized event exports

A few weeks ago, I ranted in a very technical manner about our work to consolidate analytics and events onto a single source of truth. I framed it as a behind-the-scenes post rather than something user-facing, because it was one of those boring and necessary efforts where you spend a huge amount of time wrangling internal machinery, legacy code, and bizarre historical data, only to have nothing particularly concrete to show for it except some long-awaited data reconciliation bugs that had finally been squashed. But I ended that post with a promise: that it would let us do useful things much more easily than we could before.

This is one such thing! Open any sent email, click the export icon in the analytics pane, and you now get a choice. You can download the aggregate export you could already get (the number of opens, clicks, deliveries, and so on), or you can download an itemized export: every specific event that rolls up into those numbers.

I know, I know. That is a pretty boring feature to get this excited about. But the reason I'm excited is that it is barely a feature at all, from our perspective. It is a single export that is definitionally equivalent to paging through that email's events in the API. Take a look at these two snippets:

# One export, scoped to a single email
curl -X POST https://api.buttondown.com/v1/exports \
  -H "Authorization: Token your-api-key" \
  -d '{
    "collections": ["events"],
    "parameters": {"email_ids": ["em_01j8x9v2q7f3k4m5n6p7r8s9t0"]},
    "format": "json"
  }'

# Or page through the same events yourself
curl "https://api.buttondown.com/v1/events?email_id=em_01j8x9v2q7f3k4m5n6p7r8s9t0&page=1" \
  -H "Authorization: Token your-api-key"

They return the exact same set of events, because they read from the exact same source of truth. There is no separate "export pipeline" that could drift out of sync with the analytics you see in the app, or with the events API. The export is just a filter over the events log, handed to you as a file. Which also means the same machinery works for anything else you can filter events by: a subscriber, an automation, an event type, a date range. Pass those as parameters on the exports API today, if so you dare.

Okay, I might have veered a little bit into overselling the technical side, because the user experience is, once again, boring: you click a button and get a file. But at least we got a little bit more of the former this time!