Creating Buttondown Tooling

Creating Buttondown Tooling

I thought I'd shift gears and start working on tooling for Buttondown, which delivers this newsletter. While I've been happy with the service, there are a few gaps in features that I'd like to have. Fortunately, they offer a free API for customers, and I've been using it to build tooling to fill in those gaps. I thought you might like to see how I'm doing it and get a peek into my thought process. This won't be code that you can follow along on your own, but you should be able to apply the same principles to your projects.

Archive Searching

I love that my previous newsletters are available in an online archive. However, the site doesn't have a direct search feature. If you want to find what I have written about eventing, you can't easily do that from the website. Fortunately, the content is crawled by search engines, so you could use Google.

In the Google search box, you can type site:buttondown.email/behind-the-powershell-pipeline eventing and you'll get a list of results from my newsletter.

You can read the complete archived article if you are a premium subscriber. I don't know if Google is searching the limited preview available to non-premium subscribers or the full article.

Regardless, I'd like to build something I can publish or post somewhere you can use to search the archive. Honestly, I have no idea what I want to develop yet. I have some ideas on what I want to do, but nothing definitive on a deliverable.

Exploring the Buttondown API

The first step is to use the Buttondown API to get the data I need. I will use PowerShell to do this, of course, using the Invoke-RestMethod cmdlet. Buttondown publishers, like me, can get an API key to access newsletter-related data. The API is documented, although, like much API documentation, it is aimed at developers and not scripters like myself.

Once I had my API key, the first thing I did was put it in my secrets management vault. I will need to use the API key to authenticate, so I'll need to pass it in my code. I hope it goes without saying that I don't want to hardcode this value into my code. I should pass it as a parameter.

In my development code, I'll get the API key and save it to a variable.

$bdAPI = Get-Secret -Name buttondown-api -Vault $myVault -AsPlainText

I am storing the variable as a plain text string. I could store it as a secure string, but then I'd have to convert it to a plain text string to use it in the API call. I trust the physical security of my computer, so I'm fine with this approach.

Many API requests will require some sort of authentication. When using Invoke-RestMethod, I can pass the API key in the request header.

$head = @{Authorization = "token $bdAPI" }

You need to look at your documentation to determine what value is required for authorization. In my case, Buttondown is expecting a string like token abc123def456.

Next, I need to know the endpoint. The endpoint is the URL that I will be calling. In my case, I want to get a list of all my emails. The documentation tells me that the base URI is https://api.buttondown.email/v1/. There are different endpoints for different features. For emails, I need to call https://api.buttondown.email/v1/emails/.

In my code, I like to separate the elements of the URI into variables. This makes it easier to build the URI and troubleshoot if needed.

$base = 'https://api.buttondown.email/v1'
$uri = "$base/emails"

Be careful combining elements to build your path. You don't want to end up with double slashes. The value of $uri is `https://api.buttondown.email/v1/emails

I can use Invoke-RestMethod to make the call, passing the authentication header.

$r = Invoke-RestMethod -Uri $uri -Headers $head

I've only been published on the site for a few weeks, so I only get the items I've sent.

PS D:\OneDrive...\behind-archive\> $r.count
8

This is where you need to use PowerShell to help you explore the data.

PS D:\OneDrive...\behind-archive\> $r[0] | Get-Member

   TypeName: System.Management.Automation.PSCustomObject

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
count       NoteProperty long count=8
next        NoteProperty object next=null
previous    NoteProperty object previous=null
results     NoteProperty Object[] results=System.Object[]

The API documentation tells me what kind of data I can expect but not necessarily where it is. In this case, the results property holds the data I need. This is where I see the properties defined in the API documentation.

PS D:\OneDrive...\behind-archive\> $r.results[0] | Get-Member

   TypeName: System.Management.Automation.PSCustomObject

Name                 MemberType   Definition
----                 ----------   ----------
Equals               Method       bool Equals(System.Object obj)
GetHashCode          Method       int GetHashCode()
GetType              Method       type GetType()
ToString             Method       string ToString()
absolute_url         NoteProperty string absolute_url=https://buttondown.email…
analytics            NoteProperty System.Management.Automation.PSCustomObject …
attachments          NoteProperty Object[] attachments=System.Object[]
body                 NoteProperty string body=
We're Here!
        NoteProperty string canonical_url=
creation_date        NoteProperty datetime creation_date=2/2/2024 3:57:06 PM
custom_teaser        NoteProperty string custom_teaser=
description          NoteProperty string description=
email_type           NoteProperty string email_type=public
excluded_tags        NoteProperty Object[] excluded_tags=System.Object[]
external_url         NoteProperty string external_url=
filters              NoteProperty Object[] filters=System.Object[]
id                   NoteProperty string id=3dbba30f-7699-47c7-81c6-70eb1fa2b7e7
image                NoteProperty string image=https://assets.buttondown.email…
included_tags        NoteProperty Object[] included_tags=System.Object[]
is_comments_disabled NoteProperty bool is_comments_disabled=False
metadata             NoteProperty System.Management.Automation.PSCustomObject metadata=
modification_date    NoteProperty datetime modification_date=2/2/2024 4:30:55 PM
publish_date         NoteProperty datetime publish_date=2/2/2024 4:30:00 PM
secondary_id         NoteProperty long secondary_id=177
should_send_teaser   NoteProperty bool should_send_teaser=False
slug                 NoteProperty string slug=welcome-to-our-new-home
source               NoteProperty string source=api
status               NoteProperty string status=sent
subject              NoteProperty string subject=Welcome to Our New Home

With this, I can begin considering the properties I want for my archive search.

$r.results[0] | Select-Object subject,email_type,publish_date,absolute_url,body

The data includes the full text of the article. I'll probably want to cut that down to a preview. However, I also have an idea of building an index of PowerShell commands and concepts I've written about. I could use the body property to create that index. But that's not for today.

Using API Parameters

The default behavior of the emails endpoint is to return emails I have sent. When I migrated from Substack, that content was imported into Buttondown as emails with an imported status. The API documentation tells me that I can use parameters to filter the results by using parameters. The documentation says I can use the status parameter to filter by status. Fortunately, the documentation also tells me possible values to use. Use the ? character to add parameters to the URI.

$uri = "$base/emails?status=imported"
$imported = Invoke-RestMethod -Uri $uri -Headers $head

This is where you need to be careful with defining the URI. This example works.

PS D:\OneDrive...\behind-archive\> $imported.count
175

By the way, the count property is an actual property of the object. $Imported is not an array.

PS D:\OneDrive...\behind-archive\> $imported -is [array]
False

I can't tell you how much time I spent spinning my wheels trying to use a URI like $base/emails/?status=imported only to encounter errors. See that extra slash in front of the ? character? That's what was causing the problem. I had to remove the slash to get it to work.

But I need to get emails where the status is sent or imported. I can use the status parameter to get both. This trick is in concatenating the parameters, even if they are the same.

$uri = "$base/emails?status=imported&status=sent"
$all = Invoke-RestMethod -Uri $uri -Headers $head

It is possible the API you are using might have different syntax for compound or complex parameter values, so be sure to check the documentation.

Now, I have all of my emails.

PS D:\OneDrive...\behind-archive\> $all.count
183
PS D:\OneDrive...\behind-archive\> $All.results[0..4] | Select-Object  subject,status,email_type,publish_date,absolute_url

Pagination

I know how many emails I have from the count property, but that is not what I get for results.

PS D:\OneDrive...\behind-archive\> $all.results.count
100

It is not uncommon for APIs to return data in pages or groups. In this case, it looks like Buttondown returns 100 items at a time. Typically, the next page is defined with a query parameter like ?page=2. Once again, either look to the documentation or your object for help.

$all | Get-Member -MemberType Properties

The next property is a URI that I can use to get the next page of results. I can use a do loop to get the results.

$uri = "$base/emails?status=sent&status=imported"
$all = @()
do {
    Write-Host "Processing $uri" -ForegroundColor Green
    $r = (Invoke-RestMethod -Uri $uri -Headers $head -OutVariable get).results
    $all+= $r
    $uri = $get.next
} Until ($null -eq $get.next)

I'm using the common parameter OutVariable to store the Invoke-RestMethod result. That is so I can get the next URI and use it in the loop. The Results property gets added to the array, $all.

Now, I can work with the results in $all to build my archive search.

PS D:\OneDrive...\behind-archive\> $all[0..5] | Select Subject,publish_date,email_type

subject                                publish_date         email_type
-------                                ------------         ----------
Ask Jeff                               1/30/2024 6:05:57 PM public
Add Some Zip to Your PowerShell        1/25/2024 6:12:58 PM premium
Finding Your Way on the System.IO.Path 1/23/2024 6:07:34 PM premium
More String Building                   1/18/2024 7:16:49 PM premium
Building Better Strings                1/16/2024 6:12:33 PM premium
Environmental Impact                   1/11/2024 7:04:24 PM premium

Summary

That is as far as I want to go today. So that I don't have to re-run the command, I can save the results.

$all = Import-clixml C:\scripts\behind-api-emails.xml

When I'm ready to work on this further, I can import the data and continue. I hope this gives you an idea of using an API to get data for your projects. I'll continue to work on this and share my progress with you. If you have any questions or suggestions, please let me know.

(c) 2022-2025 JDH Information Technology Solutions, Inc. - all rights reserved