canonical: https://jentic.com/apis/buttondown.email/buttondown-buttondown-api

# Buttondown Email Buttondown API

Jentic publishes the only available OpenAPI specification for Buttondown API, keeping it validated and agent-ready. Buttondown is a newsletter platform built for writers and indie publishers. This is the full surface - 118 endpoints across subscribers, emails, automations, attachments, books, coupons, comments, exports, forms, images, newsletters, notes, prices, snippets, and more. Use this spec when an integration needs deep coverage across the platform.

## For AI agents

Drive end-to-end Buttondown workflows: subscribers, emails, automations, attachments, forms, exports, and account configuration. Authenticate with a Token in the Authorization header.

## Scope

Does not handle SMS, push notifications, or transactional email for product flows - use for newsletter operations, automations, and audience management only.

## Capabilities

- Manage the full subscriber lifecycle including imports and exports
- Draft, schedule, and send newsletter emails with attachments
- Configure automations that trigger on subscriber events
- Maintain advertising units and ad slot placements
- Manage forms, snippets, and reusable email components
- Track comments, notes, and bulk actions on the audience
- Issue coupons and configure paid newsletter pricing

## Use cases

### End-to-End Newsletter Operations

Run the full newsletter lifecycle through the API - imports, drafts, scheduled sends, attachments, and post-send analytics. Publishers with engineering capacity build their own admin tooling on top of this surface. Initial integration takes a few days; ongoing operations are automated.

Example prompt: Create a newsletter email with an attachment, schedule it for 9am tomorrow, and tag the subscribers who should receive it

### Automation and Onboarding Flows

Configure Buttondown automations through the /automations endpoints to trigger emails based on subscriber events such as signup, tag changes, or paid upgrades. Indie creators use this to build welcome sequences and re-engagement flows without managing a separate marketing automation tool.

Example prompt: Create an automation that sends a welcome email when a subscriber is tagged 'paid', then verify it appears via GET on the automations collection

### Audience Export and Migration

Use the /exports endpoint to generate snapshots of subscribers, emails, or full account data. Operators use exports for migration to another platform, GDPR data subject requests, or warehouse loading. Exports run asynchronously and can be polled for completion.

Example prompt: Trigger an export of all subscribers via /exports, poll until complete, and store the resulting file in object storage

### Paid Newsletter Monetisation

Configure prices, coupons, and subscription tiers through the prices and coupons endpoints. Writers running paid newsletters use this to launch campaigns, issue discount codes, and adjust tier pricing without touching the UI. Useful for time-bound promotions.

Example prompt: Create a 20% off coupon valid for 7 days and apply it to the standard monthly price

### AI Agent Newsletter Operations

Through Jentic, an AI agent can drive any of the 118 Buttondown endpoints by intent. With this many resources, intent-based discovery removes the burden of finding the correct path manually. Useful for assistants that publish, moderate comments, or handle imports on a writer's behalf.

Example prompt: Search Jentic for 'schedule a buttondown email', load the schema for POST /emails, and execute with the body, subject, and scheduled_at fields

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/accounts/me` | Read the authenticated account profile |
| GET | `/advertising_units` | List advertising units |
| POST | `/advertising_units` | Create an advertising unit |
| GET | `/api_requests` | Audit recent API requests |
| GET | `/attachments` | List attachments |
| POST | `/attachments` | Upload an attachment |
| GET | `/advertising_units/slots` | List ad slots |

## Key resources

- **Subscribers** — Full subscriber lifecycle including bulk actions
- **Emails** — Draft, schedule, send, and analyse newsletter emails
- **Automations** — Configure triggered email sequences
- **Attachments** — Attach files to newsletter emails
- **Forms** — Create and manage signup forms
- **Exports** — Generate exports of subscribers and content
- **Newsletters** — Manage newsletter-level settings and metadata
- **Coupons / Prices** — Configure paid newsletter monetisation

## Why Jentic

- **Setup:** Wiring the full Buttondown surface by hand means learning its token scheme, mapping 118 endpoints across subscribers, automations, exports, and coupons, 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 resource ids in the URL path (`/automations/{id}`, `/emails/{id}`), so you can pin your agent to specific records instead of the whole account. You choose the operations it may call, so destructive ones like deleting an automation or triggering a draft send 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 'schedule a buttondown email' or 'export buttondown subscribers', and Jentic returns the matching operation with its input schema, which matters when the surface spans well over a hundred endpoints and the correct path is hard to find by hand.

## Related APIs

- **Buttondown API (curated)** — Lighter 10-endpoint slice focused on subscriber and email lifecycle
- **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 the agent's context.

### Can I configure automations with the Buttondown API?

Yes. The Automations resource lets you create and manage triggered email sequences such as welcome flows or re-engagement series, driven by subscriber events like tag changes or signup.

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

Buttondown does not publish hard rate limits in the spec. For high-volume operations such as bulk imports or exports, throttle requests and watch for 429 responses; back off rather than retry tight loops.

### How do I export all subscribers through Jentic?

Run pip install jentic, then search Jentic with the query 'export buttondown subscribers', load the schema for the /exports endpoint, and execute with the subscribers resource type. Poll the returned export ID until status is complete.

### How is this spec different from the smaller buttondown spec?

Both target the same base URL (https://api.buttondown.com/v1) and the same Authorization Token authentication. This spec covers 118 endpoints including automations, attachments, exports, forms, prices, and coupons; the smaller buttondown spec curates 10 endpoints around the subscriber and email lifecycle for lightweight integrations.

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

Yes. Because you run Jentic One yourself, you decide which of the 118 Buttondown operations your agent may call, so destructive ones like deleting an automation or triggering a draft send stay out of reach unless you explicitly add them. Buttondown puts resource ids in the URL path, such as `/automations/{id}` and `/emails/{id}`, so you can pin the agent to specific records rather than the whole account. Your token is stored once by your own instance and injected only at execution time, so the agent acts strictly within the operations and records you allow.