The first real signal was a draft ID: em_2gbsrbeya090fsyfv3ajwpj5tg. Not a 200 OK. Not a success message. A real, fetchable email object sitting in a Buttondown account, created by a POST call from my platform engine.

Getting there took more steps than I expected for what is nominally a simple API integration.

The starting point was a sandbox signup under @arihantdeva. I then immediately ran into the first real decision: email identity. Buttondown’s API keys are scoped to an account, and account identity matters for sender reputation. So before minting any token, I swapped the account email to arihantdeva@gmail.com and confirmed it through the inbox. Important step. Skip it and your sender identity is a stranger to your own deliverability stack.

Token scope is where I spent the most time thinking. Buttondown offers email write scope specifically, which is what I used for PE_BUTTONDOWN_TOKEN. The temptation is always to grab the broadest scope available. Saves you from coming back later. I did not. Email write only. If this token leaks through an env file permission slip or an accidental log line, the blast radius is bounded to draft creation, not account management. Narrow scopes are free insurance.

The descriptor flip, enabled=true, is the platform engine’s way of saying this channel is real now, route live content here. Before that flip, the Buttondown integration existed in config but fired nothing. After it, the next matching post command treated Buttondown as a live destination. I keep all integrations assembled but paused until I can verify them under real conditions. This is not caution, it is just not wanting to debug a live channel in production.

Verification was the honest part. I ran post, slug buttondown, kind article, force, watched the POST hit /v1/emails, and confirmed the response contained a real draft object. Status: draft. Not published, not queued. Just sitting there, fetchable, editable, real. That is the minimum bar I set for “integration is live”: something retrievable from the other side, not just a 200 response code.

What I would do differently: set up a test email POST in the first ten minutes instead of the last step. The API is straightforward, but the account email confirmation added friction I did not anticipate. If I had tried a test POST before confirming the email swap, I would have caught that earlier. Verify sender identity before anything else on newsletter platforms.

Buttondown’s API is clean. The docs are honest about what each endpoint does. No mystery about pagination, no undocumented auth behavior, no surprise rate limits on draft creation. As far as newsletter platform APIs go, this one rewards just reading the docs.