Buttondown API Integration

A comprehensive TypeScript integration for the Buttondown newsletter service, providing both a CLI interface and a Model Context Protocol (MCP) server for managing newsletters, drafts, and analytics.

Features

Multiple Interfaces:
- Command Line Interface (CLI) for direct interaction
- Model Context Protocol (MCP) server for AI/LLM integration
- Programmatic TypeScript API for custom integrations
Core Functionality:
- Email draft management (create, update, delete)
- Email scheduling system
- Analytics retrieval and formatting
- List management
- Tag management
Security:
- 1Password integration for API key management
- Environment variable support
- Secure credential handling
Developer Experience:
- Full TypeScript support
- Comprehensive type definitions
- Real API response-based types
- Built-in testing utilities

Installation

# Install using pnpm (recommended)
pnpm install

# Or using npm
npm install

# Or using yarn
yarn install

Configuration

The API key can be provided in two ways:

Environment variable:
```
export BUTTONDOWN_API_KEY=your_api_key
```
1Password CLI (recommended):
- Store your API key in 1Password at op://Development/Buttondown API/notesPlain
- The integration will automatically fetch it when needed

Usage

CLI Interface

# List all emails
buttondown emails list

# Create a new draft
buttondown draft create <file>

# Schedule an email
buttondown schedule set <draft-id> <relative-time>

# Get analytics
buttondown analytics get <draft-id>

MCP Server

Start the server:
```
pnpm mcp:start
```
Start with inspector (for development):
```
pnpm mcp:inspect
```

Available MCP tools:

list_emails: List all emails with optional status filtering

{
  "status": "draft" // Optional: "draft", "scheduled", "sent"
}

create_draft: Create a new email draft

{
  "content": "Email content in markdown",
  "title": "Optional email subject"
}

get_analytics: Get analytics for a specific email
```
{
  "draftId": "email-id-here"
}
```

schedule_draft: Schedule an email for sending

{
  "draftId": "email-id-here",
  "scheduledTime": "2024-03-27T10:00:00Z"
}

Programmatic Usage

import { ButtondownAPI } from "api-integrator";

// Initialize the client
const api = new ButtondownAPI(); // Will use 1Password or env var

// List drafts
const drafts = await api.getDrafts();

// Create a draft
const draft = await api.createEmail({
  subject: "My Newsletter",
  body: "Content here",
  status: "draft",
});

// Schedule an email
const scheduled = await api.scheduleEmail(draft.id, "2024-03-27T10:00:00Z");

// Get analytics
const analytics = await api.getEmailStats(draft.id);

Development

# Build the project
pnpm build

# Run tests
pnpm test

# Start MCP server in development mode
pnpm mcp:inspect

# Build MCP server
pnpm mcp:build

Testing

The project includes several types of tests:

Unit tests for core functionality
Integration tests for API interactions
CLI command tests
MCP server tests

Run tests with:

pnpm test

Project Structure

.
├── src/
│   ├── api/          # Core API client
│   ├── cli/          # CLI implementation
│   ├── mcp/          # MCP server
│   ├── types/        # TypeScript definitions
│   └── utils/        # Shared utilities
├── tests/            # Test files
├── api-responses/    # Cached API responses
└── memory-bank/      # Project documentation

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

ISC License - See LICENSE for details

Acknowledgments

Buttondown for their excellent newsletter service
Model Context Protocol for the AI integration framework

Categories

Current Category: buttondown

buttondown-mcp