Used for securely storing and retrieving API keys, specifically integrating with the Buttondown API by fetching credentials from a specific 1Password path.

Supports creating email content in Markdown format when creating newsletter drafts through the Buttondown API.

Supported as an alternative package manager for installing and managing the Buttondown API integration package.

Recommended package manager for installing and managing the Buttondown API integration package and its dependencies.

Provides full TypeScript support with comprehensive type definitions and real API response-based types for the Buttondown newsletter service integration.

Supported as an alternative package manager for installing and managing the Buttondown API integration package.

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

Related MCP server: ClickUp MCP Server

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

Buttondown MCP Server