Retrieving email analytics data via the API

Want to know how your last email performed? The analytics modal in the Buttondown dashboard makes it easy to see emails stats like deliveries, failures, open rates, click through rates.

But there might be times when you'd like to do something a bit more complex. Maybe you need to pull data into another tool programmatically, or build a custom dashboard. For projects like this, look no further than the Buttondown API!

Setup

Before you can use analytics, you'll need to enable Tracking in your Buttondown settings. If Tracking is not enabled, the request will still be successful but will not return any data.

Retrieving email analytics

import requests

# You can find this key in your API requests page:
# https://buttondown.email/requests
BUTTONDOWN_API_KEY = "your-api-key-here"

headers = {"Authorization": f"Token #{BUTTONDOWN_API_KEY}"}
BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/emails/{id}/analytics"

response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

Parameters

Retrieving analytics only required a single parameter: the email ID.

The email ID can be located by first listing all emails.

Results

A successful (200) request will return an object with the data for this particular email. For example:

{
    "recipients": 100,
    "deliveries": 99,
    "opens": 50,
    "clicks": 25,
    "temporary_failures": 1,
    "permanent_failures": 2,
    "unsubscriptions": 3,
    "complaints": 1
}

You can also visit the API Requests tab in your Buttondown dashboard for more details. Here's what this looks like:

Email events

Now that you have the overall data on how your email performed, you can dig a bit deeper and learn how subscribers interacted with your emails!

You can request more information about each email event by making a request like so: /events?event_type={event-type}

Email event types

Note: The name in the Analytics response differs from the Event Type name.

For example, if you wanted to learn more about your subscribers who received your newsletter, you could make the following request:

import requests

# You can find this key in your API requests page:
# https://buttondown.email/requests
BUTTONDOWN_API_KEY = "your-api-key-here"

headers = {
    "Authorization": f"Token {BUTTONDOWN_API_KEY}",
}

BASE_URL = "https://api.buttondown.email"
ENDPOINT = "/v1/emails/{id}/events?event_type=delivered"

response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers)

A successful (200) request will would return an array of all subscribers to whom your email was delivered:

   [{
      "id": "ba9fefc2-55e8-4ada-5555-057fe34d5a49",
      "subscriber_id": "9a9b7d4b-5555-45bb-bf2f-1e1d0f55555",
      "subscriber_email": "liz.lemon@tgs-nbc.com",
      "creation_date": "2013-01-01T19:38:09.725430Z",
      "metadata": {}
    },
    {
      "id": "77d51a78-53a7-45e4-9b4e-8ee83ac53c0d",
      "subscriber_id": "255130a1-ab3d-463d-5155-6569b6e9e521",
      "subscriber_email": "jack.donaghy@tgs-nbc.com",
      "creation_date": "2013-05-20T19:38:22.560044Z",
      "metadata": {}
    },
    {
      "id": "9a9b7d4b-a1ae-4e22-ab3d-3ecf7655561b",
      "subscriber_id": "36549f8b-3fgh-5555-59813-214690e8ee1b",
      "subscriber_email": "tracy.jordan@tgs-nbc.com",
      "creation_date": "2013-04-11T19:38:58.581378Z",
      "metadata": {}
    },
    {
      "id": "9ede730f-5555-4d0f-d3fg-6fc0d79043e4",
      "subscriber_id": "19a43766-5555-1234-abcd-582e6402e947",
      "subscriber_email": "kenneth.parcell@tgs-nbc.com",
      "creation_date": "2013-02-02T19:40:23.090060Z",
      "metadata": {}
    }]