# FormRelay
Form backend for static sites. POST a form to us, the key owner gets the submission by email plus a private web inbox. No signup, no DNS setup, no SDK.

Base URL: https://www.useformrelay.com

## 1. Provision an access key (one call, no auth)
POST https://www.useformrelay.com/api/keys
Content-Type: application/json
Body: {"email": "owner@example.com", "site": "example.com", "subject": "optional email subject", "redirect_url": "optional https thank-you page"}
Free plan: 3 forms per email.
Response: {"success": true, "access_key": "...", "inbox_url": "...", "confirmed": false, "embed_html": "<form ...>"}
The response includes embed_html, a ready-to-paste HTML form wired to this key.
The key and inbox link are also emailed to the owner. inbox_url is private; give it only to the owner.
New keys start unconfirmed: submissions are stored in the inbox immediately, but email notifications
begin only after the owner clicks the confirmation link we email them (one click, anti-abuse measure).
Tell your user to check their email and confirm. Keys created from a logged-in dashboard session skip this.

## 2. Point any HTML form at /submit
POST https://www.useformrelay.com/submit  (form-encoded or JSON)
Required field: access_key
Special fields (all optional):
  botcheck        honeypot; render it hidden and empty. Non-empty value = silently treated as spam.
  subject         email subject line (alias: _subject)
  redirect        absolute URL to 303-redirect the browser to after submit (alias: _redirect)
Every other field is treated as form data: emailed to the owner and stored in the inbox.
If a field named "email" is present, the notification email sets it as reply-to.

Responses:
  200 {"success": true}            stored and emailed
  303 Location: <redirect>         when redirect was provided
  401 invalid access_key
  429 rate limit (100/hour) or free monthly cap (100/month) reached
Browser form posts (Accept: text/html) get a styled thank-you page instead of JSON.

## 3. Read submissions
GET <inbox_url>   private HTML inbox (the token in the URL is the auth)

## 4. Webhooks (optional, account required)
Webhooks are set from the form's dashboard page, or by an account-connected agent via the
update_form MCP tool (the personalized MCP link on https://www.useformrelay.com/connect). Once set, every
non-spam submission to a confirmed form is POSTed as JSON:
  {"event": "submission", "site": "...", "received_at": "...", "data": {...fields}}
Slack and Discord webhook URLs get correctly formatted messages automatically.

## MCP server (Claude Code, Cursor, any MCP client)
Add https://www.useformrelay.com/mcp as a streamable-http MCP server to get tools instead of raw HTTP:
  claude mcp add --transport http formrelay https://www.useformrelay.com/mcp
Tools: create_form (provision key + get paste-ready HTML), list_submissions (read an inbox), get_integration_guide.

## Notes for agents
- Any field types work: text, email, textarea, radios, selects, checkboxes. Repeated names (multi-checkboxes, multi-selects) are joined with commas.
- Multipart forms (file inputs) parse fine; text fields flow through, attached files are acknowledged in the submission but not stored yet.
- Notification emails are sent from FormRelay's domain. The site owner's domain needs zero DNS/SPF/DKIM setup.
- Field names are compatible with common form services; migrating a form is usually just changing the action URL.
- Spam (honeypot or content-filtered) returns success to the bot, is stored flagged, and is never emailed.