Buttondown

GitHub
Integrates with
Buttondown

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:

  1. Environment variable:

    export BUTTONDOWN_API_KEY=your_api_key

  2. 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

  1. Start the server:

    pnpm mcp:start

  2. 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

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

License

ISC License - See LICENSE for details

Acknowledgments