API: Forms

Manage forms programmatically using the management API. All endpoints require a secret API key.

List forms

GET /api/forms

curl https://usepostbox.com/api/forms \
  -H "Authorization: Bearer {api_key}"

Response 200:

{
  "forms": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Contact Form",
      "slug": "contact",
      "visibility": "public",
      "submission_count": 42,
      "created_at": "2026-03-01T12:00:00Z"
    }
  ]
}

Get a form

GET /api/forms/{id}

Response 200:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Contact Form",
  "slug": "contact",
  "visibility": "public",
  "schema": {
    "fields": [
      { "name": "name", "type": "string", "required": true },
      { "name": "email", "type": "email", "required": true },
      { "name": "message", "type": "string", "required": false }
    ]
  },
  "submission_count": 42,
  "created_at": "2026-03-01T12:00:00Z"
}

Response 404:

{ "errors": "Form not found" }

Create a form

POST /api/forms

curl -X POST https://usepostbox.com/api/forms \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Feedback",
    "slug": "feedback",
    "visibility": "public",
    "fields_schema": {
      "fields": [
        {"name": "email", "type": "email", "required": true},
        {"name": "rating", "type": "number", "required": true},
        {"name": "comment", "type": "string", "required": false}
      ]
    }
  }'

Request body

Field	Type	Required	Description
`name`	string	yes	Human-readable name (1-100 characters)
`slug`	string	yes	URL-safe identifier (1-64 chars, `^[a-z0-9]+(?:-[a-z0-9]+)*$`). Unique per user.
`visibility`	string	yes	`"public"` or `"private"`
`fields_schema`	object	yes	`{ "fields": [...] }` - see Field Schema
`spam_protection_enabled`	boolean	no	Enable spam detection. Default: `false`
`spam_protection_strategy`	string	no	`"standard"` (heuristic) or `"intelligent"` (AI). Default: `"standard"`
`localisation_enabled`	boolean	no	Auto-translate submissions. Default: `false`
`smart_reply_enabled`	boolean	no	Generate AI replies. Default: `false`
`smart_replies_mode`	string	no	`"draft"` or `"auto"`. Default: `"draft"`
`knowledge_base_id`	string	no	UUID of knowledge base for smart replies. Required when `smart_reply_enabled` is `true`.
`webhook_enabled`	boolean	no	Enable webhook delivery. Default: `false`
`webhook_url`	string	no	HTTPS URL for webhooks. Required when `webhook_enabled` is `true`.
`webhook_secret`	string	no	Secret for HMAC-SHA256 signing (8-128 chars). Required when `webhook_enabled` is `true`.

Response 201 Created:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Feedback",
  "slug": "feedback",
  "visibility": "public",
  "submission_token": null,
  "created_at": "2026-03-01T10:00:00Z",
  "endpoint": "https://usepostbox.com/api/.../f/feedback"
}

Response 422 Unprocessable Entity:

{ "errors": { "slug": ["has already been taken"] } }

Update a form

PUT /api/forms/{id}

Same fields as Create, all optional. Changes to fields_schema auto-create a new versioned endpoint - see Schema Versioning.

Response 200: Same shape as Get Form.

Delete a form

DELETE /api/forms/{id}

Response 200: Returns the deleted form.

Response 404:

{ "errors": "Form not found" }