Agent Integration

Postbox is built for agents. Whether you’re using an MCP-compatible agent or building your own LLM-powered app, there are two ways to integrate.

Option 1: MCP (recommended)

If your agent supports MCP, connect it to Postbox’s MCP server. The agent gets typed tools for listing forms, reading submissions, analyzing data, and more - no glue code needed.

See the MCP integration guide for setup.

Option 2: Direct HTTP (discover-then-submit)

Any agent that can make HTTP requests can use Postbox. The pattern is two steps:

Step 1: Discover the schema

The agent sends a GET request to the form’s endpoint to learn what fields are expected:

GET https://usepostbox.com/api/.../f/contact

Response:

{
  "name": "Contact",
  "slug": "contact",
  "fields": [
    { "name": "name", "type": "string", "required": true },
    { "name": "email", "type": "email", "required": true },
    { "name": "message", "type": "string", "required": false }
  ]
}

The agent now knows: 3 fields, name and email are required, email must be a valid email, message is optional.

Step 2: Submit data

The agent constructs a payload matching the schema and POSTs it:

POST https://usepostbox.com/api/.../f/contact
Content-Type: application/json

{"name": "Agent", "email": "agent@example.com", "message": "Automated submission"}

Why discover-then-submit?

This pattern means any AI agent, script, or automation can integrate with any Postbox form without prior configuration, hardcoded field names, or an SDK. The form owner defines the schema once; consumers discover it at runtime.

For agent builders: Always discover the schema first. Don’t hardcode field names. Schemas can be versioned and updated by the form owner at any time, and the discovery endpoint always returns the current version.

Example: LLM with tool use

If you’re building an agent with tool use (function calling), define a Postbox tool:

{
  "name": "submit_to_postbox",
  "description": "Submit data to a Postbox form",
  "parameters": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "Contact name" },
      "email": { "type": "string", "description": "Contact email" },
      "message": { "type": "string", "description": "Message content" }
    },
    "required": ["name", "email"]
  }
}

When the LLM calls this tool, your code POSTs to the Postbox endpoint.

Why agents love Postbox

• No backend to build - The agent just POSTs data. Postbox handles validation, spam filtering, and storage.
• Schema as documentation - The discovery endpoint tells the agent exactly what data is expected at runtime.
• Stateless - No sessions, no cookies. Each POST is independent.
• Instant feedback - The response tells the agent immediately if the submission was accepted or rejected, with per-field validation errors.