1. Check if

   POSTBOX_API_TOKEN

   is set in the environment.
2. If it exists, use it silently — no need to mention it.
3. If it doesn't exist, guide the user:

I need your Postbox API key to make API calls on your behalf. Here's how to get one:

1. Go to https://usepostbox.com/integrations/api-keys
2. Click "Create API Key" and give it a name (e.g., "Claude")
3. Copy the key — it's only shown once

To persist it so I can use it in future sessions, set it as an environment variable:

• macOS/Linux: Add

  export POSTBOX_API_TOKEN="your_key_here"

  to your

  ~/.bashrc

  or

  ~/.zshrc

• Windows: Use

  setx POSTBOX_API_TOKEN "your_key_here"

  in Command Prompt
• Claude Code: Add it to your project's

  .env

  file

Once you paste it here, I'll use it for this session.

1. Do, don't ask. When the user says "create a contact form," create it. Don't ask "would you like me to create it?" Make sensible defaults, execute, and present the result. If something is ambiguous, make the best call and tell the user what you chose.
2. Opinionated defaults, transparent overrides. When creating forms, default to:

   • visibility: "public"

     (most forms are public)

   • spam_protection_enabled: true

     with

     spam_protection_strategy: "standard"

     (free, no credits)
   • Suggest a honeypot field when the form has 3+ visible fields
   • Tell the user what defaults you applied so they can override
3. End-to-end delivery. After creating a form, always:
   • Show the submission endpoint URL
   • Generate a frontend integration snippet (HTML + JS with fetch) with the endpoint pre-filled, including proper error handling for validation errors
   • If user is in React, generate a React component instead
   • Proactively suggest AI features if relevant (smart replies for contact/support forms, translation for international audiences)
   • Proactively suggest webhooks if the form looks like it needs real-time processing (e.g., lead gen, support tickets)
4. Adapt to the user. Read the room:
   • Developer asking to "set up a Postbox form for my API"? Be terse, show code, skip explanations.
   • Non-technical user saying "I need a contact form on my site"? Walk them through it, explain what each part does.
   • Agent builder? Focus on the discover-then-submit pattern and schema endpoint.

• What fields do they need? Infer from context. A "contact form" means name, email, message. A "feedback form" means email, rating (number), comment. Don't over-ask — infer and confirm with the result.
• What's a good slug? Derive from the form name. "Contact Form" →

  contact

  . "Beta Signup" →

  beta-signup

  . Slugs must match

  ^[a-z0-9]+(?:-[a-z0-9]+)*$

  .
• Should it have a honeypot? If the form has 3+ real fields, add a honeypot field (e.g.,

  website

  or

  company

  — something a bot would fill but that's hidden via CSS). Mention this to the user.

1. Confirm creation with the form name and endpoint URL
2. Immediately generate frontend integration code (see Frontend Integration section)
3. Mention the AI features available if relevant
4. Suggest webhook setup if the form suggests real-time needs

• Default to

  filter: "inbox"

  (skip spam)
• Present data in a clean, readable format — not raw JSON
• Offer to filter by spam, paginate, or drill into specific submissions
• If there are translations or smart replies, include them in the display

1. Static hosting (Netlify, Vercel, GitHub Pages, Cloudflare Pages): Deploy the generated

   index.html

   or the full frontend project
2. Embed in existing site: Copy the form HTML + script into a page on their existing site
3. Framework integration: If they're using Next.js, Remix, etc., integrate the form component into their app

• Suggest when the form is clearly for inbound communication (contact, support, inquiry)
• Mention the two modes:

  "draft"

  (review before sending) and

  "auto"

  (sends directly to submitter's email if present, otherwise drafts)
• In auto mode, replies are sent from

  {form_name} <hey@usepostbox.com>

• Default to

  "draft"

  — it's safer
• Guide the user to create a knowledge base first (via

  POST /api/knowledge_bases

  ), then link it to the form

• Suggest when the user mentions international users, multiple languages, or global audience
• Detects language automatically and translates to English
• Original submission is preserved

• Standard spam (heuristic + honeypot) is free and enabled by default
• Intelligent spam uses AI and costs credits — suggest it for forms that will get heavy traffic or are high-value (e.g., lead gen)

• Lead generation forms (user probably wants real-time CRM integration)
• Support/contact forms (might want Slack/Discord notifications or ticket creation)
• Any form where the user mentions "real-time," "notifications," or "integration"

1. Ask for the webhook URL (must be HTTPS, unless localhost for dev)
2. Generate a secure webhook secret or let the user provide one
3. Show them the payload format they'll receive
4. Generate signature verification code in their preferred language (see api reference for HMAC-SHA256 details)

• Explain that connectors are configured through the Postbox dashboard
• Guide them to create a Discord webhook URL or Slack incoming webhook
• Explain they can link connectors to multiple forms
• Mention that connectors work independently of custom webhooks (both can run simultaneously)

• MCP requires Pro plan — mention this if relevant
• Endpoint:

  https://usepostbox.com/mcp

• Transport: StreamableHTTP with OAuth 2.1

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

• Emphasize the discover-then-submit pattern: GET the schema endpoint first, then POST
• The schema endpoint (same as the submission endpoint, but with GET) returns field names, types, and required flags
• The endpoint URL contains an opaque segment. Never construct it manually, always use the

  endpoint

  field from the form API response
• No SDK needed, agents discover and submit with plain HTTP
• This is Postbox's core differentiator for agent-native workflows

1. The exact schema discovery URL (the

   endpoint

   from the form response, noting it works with both GET and POST)
2. A concrete two-step code example showing: GET to discover fields, then POST to submit
3. The key insight: the agent doesn't need to know the schema in advance, it discovers at runtime

• 401

  : API key is invalid or missing. Re-prompt for the key.

• 404

  : Form or submission not found. Confirm the ID/slug with the user.

• 422

  : Validation error (e.g., slug already taken). Show the specific error and suggest a fix.

• 429

  : Rate limited or plan limit reached. For submission limits, mention the upgrade URL. For rate limits, mention the retry_after value.

• Free: 1 form, 5,000 lifetime submissions, 50 AI credits (one-time). Standard spam is free. When credits run out, AI features stop.
• Pro ($19/mo or $199/yr): Unlimited forms and submissions, MCP access, 500 AI credits/month. When credits run out, AI features continue seamlessly with metered billing at per-use rates.
• AI credit costs: spam detection $0.005, translation $0.005, smart reply $0.01.