TL;DR: Form Specifications enable validation and processing of incoming messages with TOML configuration files.

With form specifications, it’s easy to validate and process incoming messages. You can now embed forms, maintain them as code, and use the visual editor for point-and-click configuration.

  • Share your form without giving access to your account
  • Check it into a versioning system / backup
  • Generate HTML forms directly
  • Use visual editor or TOML code
  • Totally optional

Update 2025: This feature now includes a full visual drag-and-drop editor alongside the TOML interface, support for 12+ field types, and real-time HTML generation. See our developer guide for modern workflows.

Here’s what a form specification looks like:

[first_name]
name = 'first_name'
field = 'text'
label = 'First Name'
placeholder = 'Mike'
required = true

[last_name]
name = 'last_name'
field = 'text'
label = 'Last Name'
placeholder = 'Doe'
required = true

[email]
name = 'email'
field = 'text'
label = 'Email'
placeholder = 'mike.doe@gmail.com'
is_email = true
required = true

[phone]
name = 'phone'
field = 'text'
label = 'Phone'
placeholder = '123-456-7890'

[message]
name = 'message'
field = 'textarea'
label = 'Message'
placeholder = 'Message'
required = true
check_spam = true
is_min = 5
on_fail = 'spam'

[kind_of_inquiry]
name = 'kind_of_inquiry'
field = 'select'
label = 'Kind of Inquiry'
options = 'General Inquiry,Technical Support,Partnership,Other'
required = true

[respond_by]
name = 'respond_by'
field = 'checkbox'
label = 'Respond by'
options = 'Email,Phone'

[settings]
discard_additional_fields = false

Here’s a quick overview of the core structure:

Field Properties:

  • name - The field identifier
  • field - Field type (text, email, textarea, number, select, checkbox, etc.)
  • label - Display label for HTML generation
  • placeholder - Placeholder text
  • required - Whether the field is mandatory

Validation Options:

  • is_email - Validates email format
  • is_url - Validates URL format
  • is_min/is_max - Length or numeric constraints
  • is_pattern - Regex pattern validation
  • check_spam - Enable spam detection (one field per form)
  • options - Valid choices for select/checkbox fields

Failure Handling: The on_fail setting controls what happens when validation fails:

  • pass - Accept submission anyway (default)
  • spam - Mark as spam
  • trash - Move to trash
  • reject - Return HTTP 400 error

Form Settings:

  • discard_additional_fields - Whether to ignore unexpected fields (required)

Modern Features (2025):

  • Visual drag-and-drop editor alongside TOML
  • 12+ field types including date, datetime, tel, url
  • Real-time HTML form generation
  • Enhanced validation with regex patterns
  • Copy-paste workflow for developer teams