Buttondown Documentation
This guide assumes a familiarity with REST APIs
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!
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 analytics only required a single parameter: the email ID.
The email ID can be located by first listing all emails.
A successful (200) request will return an object with the data for this particular email. For example:
You can also visit the API Requests tab in your Buttondown dashboard for more details. Here's what this looks like:
Not seeing the data you expect? Make sure that Tracking is enabled in your Buttondown settings.
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}
Note: The name in the Analytics response differs from the Event Type name.
Analytics response | Event Type | Description |
---|---|---|
recipients | sent | The email was sent by Buttondown. |
deliveries | delivered | The email was accepted by the recepient's email server. |
opens | opened | The recipient opened the email. |
clicks | clicked | The recipient clicked a link in the email. |
temporary_failures | bounced | The recipient's address is invalid, or misconfigured. |
permanent_failures | rejected | The email could not be delivered. |
unsubscriptions | unsubscribed | The recipient has unsubscribed from the email. |
complaints | complained | The recipient marked the email as spam. |
replies | replied | The recipient replied to your email. |
For example, if you wanted to learn more about your subscribers who received your newsletter, you could make the following request:
A successful (200) request will would return an array of all subscribers to whom your email was delivered:
As always, we’re happy to answer any questions you may have via support@buttondown.com.