Forms

Unblock turns any <form> element into a fully managed form — with honeypot spam protection, timestamp validation, rate limiting, file attachments, and email delivery — without writing JavaScript.

Setup

1. Add an Element block and set its tag to form
2. In the block's Attributes panel, add data-unbk-form

Unblock automatically injects everything needed at render time:

• Action URL — points to the REST endpoint (/wp-json/unblock/v1/form)
• Method & encoding — POST with multipart/form-data
• Honeypot field — a hidden fax_number input (CSS-hidden, catches bots)
• Timestamp token — encrypted, rejects submissions faster than 3 seconds or older than 24 hours
• Redirect URL — for non-JavaScript form submissions
• Nonce — for logged-in users

You only need to build the visible form fields. Everything else is handled.

Form ID

The data-unbk-form attribute value acts as a form identifier:

<!-- Named form -->
<form data-unbk-form="contact">...</form>

<!-- Anonymous form — uses the block's uid as fallback -->
<form data-unbk-form>...</form>

The form ID is available in PHP hooks via $context->form_id(). Use it to apply logic per form — route emails, skip notifications, or forward specific forms to external services.

Fields

Add standard HTML inputs inside the form. Unblock sanitizes and collects them automatically.

<input type="text" name="name" placeholder="Name" required>
<input type="email" name="email" placeholder="Email" required>
<textarea name="message" placeholder="Message" required></textarea>
<button type="submit">Send</button>

Limits:

• Maximum 50 fields per submission
• Maximum 10 KB per field value
• Values over 500 characters use textarea sanitization (preserves line breaks)
• Checkbox and multi-select arrays are flattened to comma-separated strings

Reserved field names — do not use these as they are handled internally:

Field	Purpose
fax_number	Honeypot (spam detection)
_unbk_ts	Timestamp token
_unbk_redirect	Redirect URL
_unbk_form_id	Form identifier
_wpnonce	WordPress nonce

File Attachments

Add file inputs to accept uploads. Files are validated in PHP's temp directory and never moved to a web-accessible location.

<input type="file" name="attachment">

Limits:

• Maximum 3 files per submission
• Maximum 5 MB per file
• Allowed extensions: jpg, jpeg, png, gif, webp, pdf, doc, docx

Extend allowed extensions with the form/allowed_extensions filter.

Responses

The form supports two response modes depending on how it's submitted:

JavaScript (fetch) — When the request includes an Accept: application/json header, the response is JSON:

{ "success": true }

On error:

{ "code": "rate_limited", "message": "Too many submissions. Please try again later.", "data": { "status": 429 } }

Standard POST — Without JavaScript, the user is redirected back to the page with a ?unbk-form=success or ?unbk-form=<error_code> query parameter.

Error codes

Code	Status	Description
honeypot	—	Spam detected (silent success, no error shown)
expired	400	Timestamp token older than 24 hours
rate_limited	429	More than 5 submissions in 15 minutes
empty_form	400	No valid fields submitted
upload_error	400	File upload failed
file_too_large	400	File exceeds 5 MB
invalid_file_type	400	File extension not allowed
mail_failed	400	Email delivery failed

Spam Protection

Three layers of protection are built in — no CAPTCHA needed:

1. Honeypot — A fax_number field hidden via CSS. Bots fill it, humans don't. Detected submissions get a silent fake success (the bot never knows).

2. Timestamp — An encrypted token records when the page loaded. Submissions faster than 3 seconds or older than 24 hours are rejected.

3. Rate limiting — Maximum 5 submissions per IP address in a 15-minute window.

Email

By default, submissions are sent to the site's admin email (Settings > General). The first field containing a valid email address is automatically used as the Reply-To header.

Customize the recipient, subject, or body with the form/email filter, or disable email entirely with form/send_email.

Integrations

Use PHP hooks to extend form behavior — forward to a CRM, store in the database, or replace the default email entirely.

Hook	Type	Description
unblock/form/processed	Action	Runs after validation, before email. Forward to external services here.
unblock/form/send_email	Filter	Return false to skip the default email notification.
unblock/form/email	Filter	Modify email recipients, subject, body, or headers.
unblock/form/fields	Filter	Add or modify sanitized fields before email.
unblock/form/client_ip	Filter	Override client IP for rate limiting (proxy support).

See the Developer documentation for a full integration example with error handling.