How AI Agents Submit Data to Postbox

Most form backends weren’t built for agents. They were built for browsers. You get a URL, maybe some docs on a separate page, and you’re expected to wire things up by hand. That works fine when a human is reading the docs and writing the integration.

It falls apart completely when an AI agent is doing the work.

An agent gets a URL and needs to answer one question: what do I send here? If the answer requires navigating to a docs site, finding the right page, parsing HTML tables, and hoping the examples are up to date — you’ve already lost. The agent either hallucinates a payload or gives up.

We built Postbox so that never happens. Every endpoint documents itself. We wrote about the full reasoning in our thesis. This post is the practical guide: how an AI agent discovers what to send, constructs a payload, submits it, and handles errors — all without a human in the loop.

The problem with “just POST to this URL”

Traditional form backends give you an endpoint and a dashboard. The endpoint accepts data. The dashboard shows you what came in. The schema — what fields exist, which are required, what types they expect — lives in the dashboard UI, or in docs, or nowhere at all.

For a developer integrating a contact form, that’s fine. For an autonomous agent that needs to collect a bug report, submit a lead, or post survey results? It’s a dead end.

Agents need machine-readable schemas at the point of interaction. Not on a separate page. Not behind authentication. At the endpoint itself.

Self-documenting endpoints

Every Postbox endpoint responds to two HTTP methods.

POST submits data. You already know this part.

GET with Accept: application/json returns the schema. The agent sends one request and gets back everything it needs:

{
  "name": "Contact Form",
  "slug": "contact",
  "endpoint": "https://usepostbox.com/api/{opaque_segment}/f/{slug}",
  "method": "POST",
  "content_type": "application/json",
  "fields": [
    { "name": "name", "type": "string", "required": true },
    { "name": "email", "type": "email", "required": true },
    { "name": "message", "type": "string", "required": false }
  ]
}

Field names. Types. Required or optional. The endpoint URL confirmed. The expected content type. Everything an agent needs to construct a valid payload, in a single GET request.

This is the same principle behind why structured forms matter — except here, the consumer isn’t a browser rendering <input> tags. It’s an LLM deciding what JSON to construct.

The agent workflow

A complete agent integration follows four steps. No human intervention required.

1. Discover the schema. The agent GETs the endpoint URL with Accept: application/json. Postbox returns the schema shown above.

2. Construct the payload. The agent reads the field definitions — names, types, required flags — and builds a JSON object that conforms to the schema. Modern LLMs from Anthropic and OpenAI handle this trivially given structured schema information.

3. Submit the data. The agent POSTs the JSON payload to the endpoint. Same URL, different method.

4. Handle the response. Postbox returns structured JSON for both success and error cases. On success, the agent gets a confirmation with the submission ID. On failure, it gets field-level errors it can use to self-correct and retry.

That’s it. No SDK. No client library. No API key rotation dance. One GET, one POST, structured responses both ways.

Error responses agents can act on

When a submission fails validation, Postbox doesn’t return a vague 400. It returns structured errors keyed by field name:

{
  "errors": {
    "email": ["is required"],
    "name": ["can't be blank"]
  }
}

An agent that receives this can read which fields failed, fix the payload, and retry. No guessing. No parsing error strings. The error format is the same whether the caller is a browser, a curl script, or an autonomous agent.

Schema versioning: agents don’t break

Here’s a subtle but critical point. When you change a form’s schema in Postbox — add a field, remove one, change a type — we create a new schema version. The endpoint URL stays the same, but the schema the endpoint expects is now the latest version.

Submissions already in flight against the old schema still validate against the schema version that was active when they were sent. Agents holding your endpoint URL don’t suddenly start getting validation errors because you added a field last Tuesday.

This is the difference between “has an API” and “designed for programmatic consumption.” We wrote about the browser side of this in the HTML form guide, but it matters even more for agents that run unattended.

Private forms and authentication

Not every endpoint should be open to the world. For forms that require authentication, Postbox uses Bearer token auth. The agent includes your API key in the Authorization header:

Authorization: Bearer your_api_key

The schema discovery step works the same way — GET with the auth header, get the schema back. The only difference is that unauthenticated requests get a 401 instead of the schema.

A concrete example

Imagine you give Claude a task: “Collect feedback from our beta users and submit it to our Postbox endpoint” — and you paste the endpoint URL from your Integration tab.

Claude doesn’t need a manual. It GETs the URL, sees the schema — rating (integer, required), feedback (string, required), email (email, optional) — constructs the payload from the user’s input, POSTs it, and confirms success. If it sends a string where an integer was expected, it gets a structured error, fixes the payload, and retries.

No integration guide. No SDK install. No human wiring up the connection. The endpoint told the agent everything it needed to know.

This works with any agent framework. Any LLM that can make HTTP requests. Any automation pipeline that can parse JSON. The protocol is HTTP. The schema is JSON. There’s nothing proprietary to learn.

Going further with MCP

If the agent supports the Model Context Protocol, you don’t even need to give it a URL.

MCP lets an agent discover your Postbox forms as callable tools — browse available forms, read their schemas, and submit data, all through a standardized tool interface. The agent doesn’t need to know about HTTP methods or endpoint URLs. It just sees “submit_feedback” as a tool with typed parameters.

We cover this in detail in the MCP submission guide. If you’re building with Claude Code, OpenClaw, or any MCP-compatible agent, it’s worth reading.

What “agent-native” actually means

We call Postbox agent-native, and this is what we mean by it. It’s not an API bolted onto a product designed for humans clicking through a dashboard. It’s a system where every interaction — schema discovery, submission, error handling, authentication — is designed for programmatic consumption from the ground up.

Browsers can use it. HTML forms work great. Scripts work great. But agents don’t need special accommodation. They’re first-class consumers.

The endpoint documents itself. The errors are structured. The schema versions don’t break existing integrations. Authentication is a header, not a session cookie. That’s what agent-native means in practice.

Postbox also runs spam filtering, auto-translation, and smart replies on incoming submissions — all of which work identically whether the data came from a browser, a script, or an agent. The post-submit layer doesn’t care who sent it. It just does its job.

Start collecting

Create an account at usepostbox.com, set up a form, and give the endpoint URL to an agent. That’s the whole integration. The agent handles the rest.