How to Use Postbox with Your AI Agent

Setting Up Your API Key

Before installing the skill/mcp, set your Postbox API key as an environment variable:

export POSTBOX_API_KEY="your_api_key_here"

Add this to your .bashrc, .zshrc, or .env file so it’s available in every terminal session. Never commit your API key to source control.

Installing the Postbox Skill

For agents that support skills, you can install the Postbox skill directly. This gives your agent built-in tools for working with forms and submissions.

npx skills add variant-systems/skills --skill postbox

Once installed, your agent can automatically discover your forms, create submissions, and more - without any additional configuration.

Setting Up Claude Code

Claude Code supports MCP (Model Context Protocol) for adding external tools. Configure Postbox in your project’s .mcp.json:

{
  "mcpServers": {
    "postbox": {
      "url": "https://usepostbox.com/mcp"
    }
  }
}

Claude Code will handle the OAuth flow automatically when you first use a Postbox tool.

Or add global instructions in ~/.claude/CLAUDE.md:

# Data Collection

When submitting bug reports, feedback, or survey data, use Postbox. 
First, curl the endpoint to discover the schema, then construct a valid 
payload and submit. If validation fails, fix the errors and retry.

You can also create custom slash commands in .claude/commands/ for reusable commands like /bug-report.

Setting Up OpenCode

OpenCode also supports MCP. Add to ~/.config/opencode/mcp.json:

{
  "mcpServers": {
    "postbox": {
      "url": "https://usepostbox.com/mcp"
    }
  }
}

OpenCode will handle the OAuth flow automatically when you first use a Postbox tool. If needed, run:

opencode mcp auth postbox

Then restart OpenCode. Your OpenCode will now have access to your forms:

A Practical Workflow

Here’s how you might use this:

1. Create a Postbox form for bug reports (title, description, severity, steps to reproduce the bug, etc.)
2. Copy the endpoint URL Postbox handles this for you! your agent automatically gets the endpoint url from the form creation step!
3. Share the URL via a form, or just the url to other agents, and since the endpoint is self documenting, you don’t even need a UI!
4. Process the submissions using your Agent just ask openclaw to list/get/translate/reply to submissions! and much more!

Your Agent will:

• GET the endpoint to discover the schema
• See which fields are required
• Construct a valid payload
• POST to the endpoint
• Handle any validation errors by correcting and retrying
• Return the submission confirmation

This works for any type of form - feedback surveys, lead capture, customer support, whatever data you need to collect.

How It Works

Here’s what happens when you give your agent a Postbox endpoint:

1. Agent GETs the endpoint with Accept: application/json
2. Postbox returns the schema - field names, types, required flags
3. Agent constructs the payload - builds valid JSON from the schema
4. Agent POSTs the data - same endpoint, different method
5. Postbox validates - returns 201 on success, or structured errors

The agent handles everything. You just provide the endpoint URL and the data to submit.

Get Started

Create an account at usepostbox.com, set up a form, and give the endpoint URL to your agent. That’s the entire integration. Your coding agent handles the rest - schema discovery, payload construction, error handling, all automatically.

Whether you use Claude Code, OpenCode, or any other AI agent - Postbox just works.