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
- Store your API key in 1Password at
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