Skill

Overview

The Postbox skill gives AI coding agents the context they need to integrate with the Postbox API - create forms, submit data, configure processing pipelines, and manage submissions. With the skill installed, your AI agent can generate accurate integration code without you having to copy-paste documentation.

There are two ways to set it up: connect the MCP server for live, interactive access (Pro plan), or add a skill file for static API context (all plans).

Installation

MCP Server (Pro)

The MCP server gives your AI agent live access to your Postbox data - it can list forms, read submissions, run spam analysis, draft replies, and more.

1. Add the MCP server config

   Add Postbox to your agent’s MCP configuration:

   Claude Code

   Add to your project’s .mcp.json or global settings:

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

   Cursor

   Add to .cursor/mcp.json in your project root:

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

   VS Code (Copilot)

   Add to .vscode/mcp.json in your project root:

   {
     "servers": {
       "postbox": {
         "type": "http",
         "url": "https://usepostbox.com/mcp"
       }
     }
   }

   Windsurf

   Add to ~/.codeium/windsurf/mcp_config.json:

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

   OpenCode

   Add to ~/.config/opencode/config.toml:

   [mcp.postbox]
   type = "http"
   url = "https://usepostbox.com/mcp"

2. Authenticate

   The first time your agent uses a Postbox tool, it will trigger an OAuth flow. Sign in to your Postbox account and approve access.

3. Verify the connection

   Ask your agent:

   “List my Postbox forms”

   It should call the list_forms tool and return your forms. If you don’t have any yet, it will return an empty list.

Skill File (All Plans)

A skill file gives your AI agent static context about the Postbox API so it can generate correct integration code.

1. Set up your API key

   Generate an API key at Integrations > API Keys and add it to your environment:

   export POSTBOX_API_TOKEN=your_api_key_here

   Or add to your project’s .env file:

   POSTBOX_API_TOKEN=your_api_key_here

2. Add the skill to your project

   Claude Code

   Add to your project’s CLAUDE.md:

   ## Postbox Integration
   
   API reference: https://usepostbox.com/llms-full.txt
   API key is in POSTBOX_API_TOKEN environment variable.
   Base URL: https://usepostbox.com

   Claude Code will fetch and read the full API reference automatically when needed.

   Cursor

   Create .cursor/rules/postbox.mdc in your project root:

   ---
   description: Postbox API integration context
   globs:
   alwaysApply: false
   ---
   
   ## Postbox Integration
   
   API reference: https://usepostbox.com/llms-full.txt
   API key is in POSTBOX_API_TOKEN environment variable.
   Base URL: https://usepostbox.com

   Windsurf

   Add to .windsurfrules in your project root:

   ## Postbox Integration
   
   API reference: https://usepostbox.com/llms-full.txt
   API key is in POSTBOX_API_TOKEN environment variable.
   Base URL: https://usepostbox.com

3. Verify the installation

   Ask your agent:

   “Create a Postbox contact form with name, email, and message fields, then show me the endpoint URL”

   The agent should generate code that calls POST /api/forms with the correct fields_schema format and use Bearer token authentication.

Supported Platforms

The skill works with any AI coding agent that supports MCP or custom context files:

Platform	MCP	Skill File
Claude Code	Yes	Yes (CLAUDE.md)
Cursor	Yes	Yes (.cursor/rules/)
Windsurf	Yes	Yes (.windsurfrules)
VS Code (Copilot)	Yes	Yes (.github/copilot-instructions.md)
OpenCode	Yes	-
Codex	-	Yes
Gemini CLI	-	Yes (GEMINI.md)
Amp	-	Yes

Sample Prompts

Once installed, try these prompts with your AI agent:

Creating forms:

“Create a Postbox feedback form with fields for email (required), rating (number, required), and comment (optional)”

Submitting data:

“Write a script that submits deploy notifications to my Postbox form after each CI build”

Reading submissions:

“Show me the last 10 submissions for my contact form and summarize the common themes”

Full integration:

“Build a contact form component that submits to my Postbox endpoint, handles validation errors inline, and shows a success message”

With MCP (Pro):

“Analyze my form submissions from the past week - how many were spam? What languages were they in?”

“Draft a reply to the latest support submission using my knowledge base”

Prerequisites

1. Create a Postbox account

   Sign up at usepostbox.com. A “Try Me” form is created automatically so you can start testing immediately.

2. Generate an API key

   Go to Integrations > API Keys, click Generate New Key, name it, and copy the key. Store it as POSTBOX_API_TOKEN in your environment.

   Caution

   The key is shown only once. Store it immediately.

3. For MCP: Upgrade to Pro

   The MCP server requires a Pro plan ($19/mo or $199/yr). The skill file approach works on all plans.

What’s Included

Authentication

All management API requests use Bearer token authentication:

Authorization: Bearer {api_key}

Public form endpoints (submitting data, discovering schemas) require no authentication. Private forms require a submission_token as a Bearer token.

Form Operations

Method	Endpoint	Description
POST	/api/forms	Create a form
GET	/api/forms	List all forms
GET	/api/forms/{id}	Get form details
PUT	/api/forms/{id}	Update a form
DELETE	/api/forms/{id}	Delete a form

Forms accept a fields_schema with typed fields (string, email, number, boolean, date), each with name, type, required, and optional honeypot properties.

Submission Operations

Method	Endpoint	Description
POST	/api/.../f/{slug}	Submit data (public endpoint)
GET	/api/.../f/{slug}	Discover form schema
GET	/api/forms/{id}/submissions	List submissions
GET	/api/forms/{id}/submissions/{id}	Get a submission
DELETE	/api/forms/{id}/submissions/{id}	Delete a submission

Submissions accept Content-Type: application/json only. The submission endpoint URL is returned in the endpoint field when creating or retrieving a form.

Knowledge Bases

Method	Endpoint	Description
POST	/api/knowledge_bases	Create a knowledge base
GET	/api/knowledge_bases	List knowledge bases
GET	/api/knowledge_bases/{id}	Get a knowledge base
PUT	/api/knowledge_bases/{id}	Update a knowledge base
DELETE	/api/knowledge_bases/{id}	Delete a knowledge base

Knowledge bases contain text content (FAQs, docs, policies) that power smart replies.

AI Features

All AI features are configurable per-form and use AI credits:

Feature	Setting	Credit Cost
Spam detection (AI)	spam_protection_strategy: "intelligent"	$0.005/submission
Translation	localisation_enabled: true	$0.005/submission
Smart replies	smart_reply_enabled: true + knowledge_base_id	$0.01/reply

Standard spam protection (heuristics, honeypot) is free and uses no credits.

MCP Tools (Pro)

When connected via MCP, agents have access to:

Tool	Description
list_forms	List all forms
get_form	Get form details and schema
list_submissions	List submissions with filtering
get_submission	Get full submission details
get_dashboard_stats	Overview statistics
translate_submission	Translate a submission on demand
analyze_spam	Run AI spam analysis
draft_reply	Generate a reply using a knowledge base
summarize_submissions	Summarize recent submissions with insights