Buttondown

🚀 Buttondown API Integration

A comprehensive TypeScript implementation integrating the Buttondown newsletter service, offering a Command Line Interface (CLI) 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 Functions:

  • Newsletter draft management (create, update, delete).
  • Newsletter scheduling system.
  • Analytics data retrieval and formatting.
  • List management.
  • Tag management.

• Security:

  • 1Password integration for API key management.
  • Environment variable support.
  • Secure credential handling.

• Developer Experience:

  • Comprehensive TypeScript support.
  • Complete type definitions.
  • Types based on real API responses.
  • Built - in testing tools.

📦 Installation

# Use pnpm (recommended)
pnpm install

# Or use npm
npm install

# Or use yarn
yarn install

📚 Documentation

Configuration

API keys can be provided in the following two ways:

1. Environment variables:

   export BUTTONDOWN_API_KEY=your_api_key
   

2. 1Password CLI (recommended):

   • Store the API key in op://Development/Buttondown API/notesPlain in 1Password.
   • The integration will automatically retrieve it when needed.

Usage

Command Line Interface (CLI)

# List all newsletters
buttondown emails list

# Create a new draft
buttondown emails draft new

# Send a test email
buttonton emails send --test

# Get help information
buttondown help

MCP Server

The MCP server is an interface for interacting with AI models, supporting the following operations:

• Get context:

  curl -X GET "http://localhost:1234/api/v1/context"
  

• Set context:

  curl -X POST "http://localhost:1234/api/v1/context" \
    -H "Content-Type: application/json" \
    -d '{"context": {"key": "value"}}'
  

Programmatic Usage

import { Buttondown } from '@buttondown/buttondown-api';

const buttondown = new Buttondown({
  apiKey: 'your_api_key',
});

// Create a new draft
async function createDraft() {
  try {
    const response = await buttondown.drafts.create();
    console.log('Draft created:', response);
  } catch (error) {
    console.error('Error:', error);
  }
}

Development

# Install dependencies
npm install

# Start the development server
npm run dev

# Run tests
npm test

Project Structure

• src/: Contains the main source code files.
• public/: Contains the built static resource files.
• node_modules/: Automatically installed dependencies.
• package.json: Project dependency management and running scripts.
• .env: Environment variable configuration file.

Contribution Guidelines

1. Fork the repository:

   git clone https://github.com/yourusername/buttondown-api.git
   cd buttondown-api
   

2. Create a feature branch:

   git checkout -b feature/new-feature
   

3. Commit changes:

   git add .
   git commit -m "Add new feature"
   git push origin feature/new-feature
   

4. Create a pull request: After submission, visit GitHub to create a new pull request.

📄 License

This project is licensed under the MIT License. See LICENSE for details.

👏 Acknowledgments

• Buttondown Thanks for its excellent newsletter service.
• Model Context Protocol Thanks for the AI integration framework.