canonical: https://jentic.com/apis/buttondown.com/buttondown

# Buttondown API

Jentic publishes the only available OpenAPI specification for Buttondown API, keeping it validated and agent-ready. Buttondown is a minimalist newsletter platform built for writers, indie creators, and small publications. This spec covers programmatic management of subscribers, emails, and tags - the core resources needed to drive a newsletter from outside the Buttondown UI. Authentication uses a token-based API key passed in the Authorization header.

## For AI agents

Manage Buttondown newsletters: create and update subscribers, send and edit emails, and organise content with tags. Authenticate with a Token in the Authorization header.

## Scope

Does not handle SMS, transactional email delivery for product flows, or marketing automation journeys - use for newsletter subscriber, email, and tag management only.

## Capabilities

- Add new subscribers and update their metadata
- Remove subscribers from a newsletter list
- Draft, schedule, and send newsletter emails
- Update existing email drafts before sending
- Organise subscribers and emails with tags
- Look up an individual subscriber by ID or email

## Use cases

### Subscriber Sync from External Forms

Push new subscribers into Buttondown from external signup forms, landing pages, or CRM systems. Indie writers and small teams use this to keep Buttondown in sync without manual exports. A typical sync runs in seconds per subscriber via POST /subscribers.

Example prompt: Read new signups from a Google Sheet and POST each row to /subscribers with email and tag fields

### Automated Newsletter Drafting

Generate newsletter drafts from external content sources - blog posts, RSS feeds, or AI summaries - and create them in Buttondown via POST /emails. Editors review the draft in the Buttondown UI before scheduling. Reduces drafting time from 30 minutes to a few seconds per issue.

Example prompt: Summarise the latest five blog posts, format them into a Markdown newsletter, and POST to /emails as a draft

### Tag-Based Audience Segmentation

Use the /tags endpoint to create and manage tags applied to subscribers and emails. Operators use this to segment audiences for targeted sends or to track campaign performance over time. Tags can be created and listed in a single agent run.

Example prompt: Create a tag named 'paid-tier', list all subscribers, and apply the tag to those flagged as paid in the source CRM

### AI Agent Newsletter Operations

Through Jentic, an AI agent can drive Buttondown end-to-end - adding subscribers, drafting emails, and managing tags - using natural language intent. Agents discover the right operation by searching, load the schema, and execute without scraping the docs.

Example prompt: Search Jentic for 'send a buttondown newsletter', load the schema for POST /emails, and execute with subject, body, and recipient list

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/subscribers` | Create a new subscriber |
| GET | `/subscribers/{idOrEmail}` | Look up a subscriber by ID or email |
| PATCH | `/subscribers/{idOrEmail}` | Update a subscriber |
| POST | `/emails` | Create a newsletter email |
| GET | `/emails` | List emails |
| PATCH | `/emails/{id}` | Update an email draft |
| POST | `/tags` | Create a tag |

## Key resources

- **Subscribers** — Manage the newsletter audience - create, list, update, and delete subscriber records
- **Emails** — Draft, list, update, and delete newsletter emails
- **Tags** — Create and list tags used to segment subscribers and emails

## Why Jentic

- **Setup:** Wiring Buttondown by hand means learning its token scheme, remembering the odd 'Token YOUR_API_KEY' prefix the Authorization header expects, and writing your own backoff for the undocumented 429s. Through Jentic you install once, import the Buttondown API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Buttondown puts the subscriber or email id in the URL path (`/subscribers/{idOrEmail}`, `/emails/{id}`), so you can pin your agent to specific records rather than the whole audience. You choose the operations it may call, so destructive ones like deleting a subscriber or removing an email draft are not included unless you add them.
- **Credential handling:** Your Buttondown token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a buttondown subscriber' or 'send a buttondown newsletter', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Buttondown API (full)** — Larger Buttondown spec covering 118 endpoints across the full surface
- **ConvertKit (Kit)** — Creator-focused email platform with automations and tags
- **Beehiiv** — Newsletter platform with monetisation and referral features
- **MailerLite** — Broader email marketing platform with campaigns and landing pages

## FAQ

### Why is there no official OpenAPI spec for Buttondown API?

Buttondown does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Buttondown API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Buttondown API use?

Buttondown uses a token-based API key passed in the Authorization header in the format 'Token YOUR_API_KEY'. Through Jentic, the key is stored in the encrypted vault and never enters an agent's context.

### Can I send a newsletter through the Buttondown API?

Yes. POST to /emails creates a new newsletter email; PATCH to `/emails/{id}` updates a draft. The API supports the full draft, edit, and send lifecycle for newsletter content.

### What are the rate limits for the Buttondown API?

Buttondown does not publish hard rate limits in the spec. For batch subscriber syncs, space requests at a moderate cadence and watch for 429 responses; back off when they appear rather than retrying tight loops.

### How do I add a subscriber through Jentic?

Run pip install jentic, then search Jentic with the query 'add a buttondown subscriber', load the schema for POST /subscribers, and execute with the email and any optional tag or metadata fields.

### Can I look up a subscriber by email address?

Yes. GET `/subscribers/{idOrEmail}` accepts either the subscriber's UUID or their email address as the path parameter, returning the full subscriber record if it exists.

### Can I limit what my agent is allowed to do with the Buttondown API?

Yes. Because you run Jentic One yourself, your own rules decide which Buttondown operations and credentials the agent may use. You can grant it read and create calls like GET `/subscribers/{idOrEmail}` and POST /subscribers while withholding destructive ones such as deleting a subscriber or removing an email draft. Since the subscriber or email id sits in the URL path (`/subscribers/{idOrEmail}`, `/emails/{id}`), you can also pin the agent to specific records rather than the whole audience.