Skip to content

Agent-native by design

Give your agent the form job.

It builds, wires and tests a real form before you sign up. You claim it — the agent turns on delivery.

Read llms.txtOpenAPI contractAgent guide

One instruction

Hand it over without writing a setup guide.

Copy the prompt into your coding agent. The Postbag skill gives it the contract and the safe order of operations.

Install the Postbag skill with `npx skills add faahim/postbag --skill postbag`, then use it to set up and test a working contact form for this site.
npx skills add faahim/postbag --skill postbag
POSTBAG_API_KEY=pb_live_… npx -y @postbag/mcp
npx postbag login
npx postbag init

Works with Claude Code, Cursor, Codex, Windsurf, or any agent that can read a URL.

The working handoff

No credentials to routed Delivery.

The Form keeps one identity throughout. What changes is the authority around it.

  1. 01

    Anonymous

    Create

    No account
  2. 02

    Sandbox

    Prove receipt

    Up to five tests
  3. 03

    Human boundary

    Claim

    Same Form id
  4. 04

    Organization

    Route

    New Deliveries

Before signup

Create and prove receipt.

The create response is the only place the sandbox capability appears. Keep it until claim or expiry.

create → submit → inspect 
$ key=$(node -e 'console.log(crypto.randomUUID())')
$ curl -X POST https://postbag.dev/v1/public/sandboxes \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $key" \
  -d '{"name":"Contact","origin":"https://example.com"}'
# stable submit_url, sandbox_token, embed, claim_url and next[]

$ curl -X POST https://postbag.dev/s/fm_8f3kq2 \
  -H "content-type: application/json" \
  -d '{"email":"[email protected]","message":"test"}'

$ curl https://postbag.dev/v1/public/sandboxes/fm_8f3kq2 \
  -H "Authorization: Sandbox pbs_…"

After the human step

Claim, connect, deliver.

Claim keeps the Form stable. Outbound Delivery starts only after the agent adds a Destination and Route.

authenticate → claim → route 
$ postbag login
# the human reads the emailed code and gives it to the agent

$ postbag sandbox claim --token pbs_…
# same Form id and submit URL

# create a Destination and Route for the claimed Form
$ postbag destinations create …
$ postbag routes create …

# submit a new test and poll the returned Delivery id
$ postbag deliveries get dl_a91x02

Not an AI add-on

Agent-native is a product property.

Discoverable
llms.txt, OpenAPI and literal next calls tell an agent where to begin and what to do after every create.
Verifiable
Receipt and Delivery are separate proofs. The agent can inspect both instead of assuming a 200 means the work is done.
Safe to repeat
Idempotency keys and if_exists keep retries boring, which is exactly what setup automation needs.
Complete
The SDK, CLI, MCP server and raw HTTP contract reach the same product capabilities as the dashboard.

Leave a clean trail

The next agent should not have to guess.

Keep public Form wiring in postbag.json and a short note in the repository instructions. Keep secrets somewhere else.

AGENTS.md 
# AGENTS.md
Forms on this site post to Postbag.
Read postbag.json for form_id, submit_url and project.

When changing a Form:
1. Use the returned submit URL. Never construct one.
2. Send a _test Submission.
3. Poll its Delivery until sent.
4. Keep API keys and sandbox capabilities out of the repo.

Agent questions

What does an agent need to start?
No account or API key. POST /v1/public/sandboxes creates a bounded 24-hour sandbox Form with a stable submit URL. The agent can wire it into the site and verify up to five stored test Submissions.
How does the sandbox capability work?
The capability token appears only in the create response. It is not shown again, so the agent must store it safely. The same token can read the sandbox and authorize claim until the Form is claimed or expires.
Can a sandbox send email or webhooks?
No. Before claim it cannot create Destinations, Routes or outbound Deliveries. Claiming preserves the Form id and submit URL. A Destination and Route must then be configured before new Submissions can deliver. Sandbox tests never deliver retroactively.
How does an agent get a full API key?
Email-code authentication uses two calls with one human step between them. The user passes the emailed code to the agent, and verification returns a pb_live_… key. postbag login runs the same flow. Browser OAuth may also be available when the Postbag instance has a provider configured.
How does an agent prove the Form works?
Before claim, it posts to the stable submit URL and reads the stored test with the sandbox capability. After claim, Destination and Route setup, a new _test Submission returns Delivery ids the agent can poll until sent.
Which clients are available?
The TypeScript SDK, postbag CLI and @postbag/mcp server are published on npm. They are thin clients over the same public /v1 contract described by /openapi.json.
Can setup be safely retried?
Every POST under /v1 accepts an Idempotency-Key. Creates also accept if_exists: "return", so a repeated setup can return the existing object instead of making a duplicate.

Let your agent start.

It can leave a working, tested Form behind. You only step in when it is time to claim and deliver.

Create a form Read the agent guide