Forms

A form is a named data collection point. When you create a form, Postbox gives you an endpoint. POST data to it from anywhere.

Creating a form

In the dashboard, click New Form and configure:

• Name - Human-readable label (e.g., “Contact Form”), 1-100 characters
• Slug - URL-safe identifier (e.g., contact), used in your endpoint URL. Pattern: a-z, 0-9, hyphens only. Unique per account.
• Visibility - Public or private (see below)
• Fields - The schema defining what data you accept

Fields and schema

Each form has a fields_schema - a list of fields with types and validation:

Property	Description
name	Field identifier (used as the JSON key in submissions)
type	Data type: string, email, number, boolean, date
required	Whether the field must be present
honeypot	Whether the field is a spam trap (see Honeypot Fields)

Field types

Type	Validation	Example
string	Must be a string	"Hello world"
email	Valid email format (must contain @)	"user@example.com"
number	Integer or float	42 or 3.14
boolean	true or false	true
date	ISO 8601 date string	"2026-03-01"

Example schema

A contact form might have:

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

Visibility

Forms can be public or private:

• Public - Anyone can submit to the endpoint, no authentication needed
• Private - Submissions require Authorization: Bearer {submission_token}. The token is returned once when the form is created. Store it immediately - it cannot be retrieved again.

Versioning

When you change a form’s schema, Postbox creates a new version. The key guarantee:

• New submissions use the latest schema and validation
• Existing URLs continue to work - nothing breaks
• Old submissions retain their original shape

This means you can iterate on your form freely without worrying about breaking integrations.

Form settings

Beyond the schema, each form has processing settings:

• Spam protection - Enable heuristic detection (standard) or AI-powered analysis (intelligent)
• Auto-translation - Detect language and translate submissions (uses AI credits)
• Smart replies - AI-generated responses using a knowledge base (uses AI credits)
• Webhooks - Push submission data to your server in real-time

Endpoints

Every form gets a unique submission URL:

https://usepostbox.com/api/.../f/{slug}

The ... is an opaque, server-generated segment. Don’t construct this URL manually - use the endpoint field from the form creation or retrieval response.