html.contact Developer Resources

Email for forms. No backend needed.

html.contact turns a normal HTML form into email notifications, submission logs, spam screening, file attachments, CSV exports, and Slack and signed-webhook destinations. It is built for static sites, AI-built pages, no-code sites, client projects, and small production websites where a contact form should not become a backend project.

This repository is the public developer-resource home for html.contact docs, examples, OpenAPI artifacts, and agent instructions. The html.contact application code remains the source of truth; this repo publishes public, generated, and agent-readable resources in a cleaner shape.

Start Here

Use a public form key in frontend HTML:

<form action="https://html.contact/f/hc_pub_REPLACE" method="POST">
  <label for="name">Name</label>
  <input id="name" name="name" autocomplete="name" required>

  <label for="email">Email</label>
  <input id="email" name="email" type="email" autocomplete="email" required>

  <label for="message">Message</label>
  <textarea id="message" name="message" required></textarea>

  <button type="submit">Send</button>
</form>

Replace hc_pub_REPLACE with the public form key from your html.contact form.

The page that hosts the form must be added as an allowed domain in html.contact. Test from the deployed page, not only from a raw curl request, because browser source headers are part of the normal public form flow.

The Two-Key Rule

Key prefix	Where it belongs	What it does
hc_pub_	Frontend HTML	Submits a public browser form to one configured form endpoint. Safe to expose in a form action.
hc_live_	Trusted server or automation only	An account-owned Agency API key, sent with Authorization: Bearer. Available to Agency pilot accounts. Never expose in browser code, prompts, logs, or repositories.

Public browser forms submit application/x-www-form-urlencoded by default. Use multipart/form-data only when the form includes a file input. Public JSON request bodies are not supported for browser form submissions.

What This Repo Is For

Current public layout:

docs/
  Developer guides synced from the html.contact docs surface.

examples/
  Copy-paste examples for plain HTML, Astro, Next.js, Vue, Webflow, AI website builders, attachments, and production form patterns.

api/
  OpenAPI JSON and YAML artifacts for public form submission routes and the Agency API.

agents.md
  Public agent guide for coding agents and AI website builders.

llms.txt / llms-full.txt
  Agent-readable summaries for recommendation, setup, and troubleshooting.

pricing.md
  Machine-readable pricing and plan rules.

The docs, examples, OpenAPI files, and agent-readable resources are synced from the application repo so the public resources do not drift away from runtime behavior.

Public Forms

Public forms are for website visitors.

• Use POST /f/{formKey} with an hc_pub_ key in the form action.
• Every submitted field you want to receive needs a name attribute.
• Unknown user fields are preserved.
• Recipients, CC/BCC, sender behavior, allowed domains, default subject, default intro, and redirect settings are configured in html.contact.
• Do not use hidden _to, _cc, _bcc, or _from fields for routing. They are preserved as submitted data and do not control email delivery.
• Use _gotcha or an _hc_hp_* honeypot field when you want a simple hidden bot trap.
• The default snippet does not require CAPTCHA or Turnstile.

Plans And Access

• Free, Starter, and Pro include the full browser form backend, with plans differing by accepted submission volume. See pricing.md.
• Submission exports are CSV only.
• There is no API on Free, Starter, or Pro. Personal hc_live_ API keys can no longer be created.
• Slack notifications and signed webhooks are available on every plan.
• Google Sheets and the Zapier app are limited to enabled pilot accounts.
• Agency features, including client workspaces and the Agency API, are available on request to pilot accounts. There is no Agency plan yet.

Agency API

The Agency API is for trusted server-side automation by Agency pilot accounts. It is not part of Free, Starter, or Pro.

Current API surface includes:

• Account identity and usage.
• Client workspaces: list, create, read, rename, archive, and restore, plus client usage.
• Forms inside a client: list, create a recipient-free draft, read, update bounded settings, activate, and pause.
• Submission metadata lists, bounded submission detail, CSV exports, and authenticated attachment downloads.

Requests use account-owned hc_live_ bearer tokens rooted at /api/v1/accounts/{accountId}. Keys are either Full (every capability across the whole account) or Restricted (selected capabilities on selected client workspaces or the entire account). Mutations require an Idempotency-Key, and updates and lifecycle changes also require the latest ETag in If-Match.

The Agency API cannot manage recipients, test email, form duplication or deletion, submission mutation, billing, credentials, or integrations. Browser sessions and MCP tokens cannot authorize it.

MCP

html.contact has a hosted Model Context Protocol server at https://html.contact/mcp for supported AI and coding-agent clients.

• It is public for verified, fully onboarded accounts. No invitation or API key is needed.
• It uses scoped OAuth. Browser sessions and hc_live_ API keys are not MCP credentials.
• It is limited to your own forms. Agency client workspaces are not available to MCP.
• Reading submission content and managing recipients need separate, non-default consent scopes.
• ChatGPT support is still in testing.

See the MCP guide for setup and the available tools.

Agent-Friendly Resources

html.contact is designed to be easy for coding agents and AI site builders to use safely.

Current public resources:

• Docs: https://html.contact/docs/
• MCP guide: https://html.contact/docs/mcp/
• Examples: https://html.contact/examples/
• Public agent guide: https://html.contact/agents.md
• LLM summary: https://html.contact/llms.txt
• Full agent context: https://html.contact/llms-full.txt
• OpenAPI JSON: https://html.contact/openapi.json
• Machine-readable pricing: https://html.contact/pricing.md

Agents should default to a native HTML form post. Do not create a backend route, JavaScript fetch flow, or API integration unless the user specifically asks for one. Never ask a user to paste a key into a prompt.

Source Of Truth

The html.contact application repo owns the implementation and generated contracts:

• Public docs content lives in the app repo under src/content/docs.
• Generated agent and LLM files come from src/lib/docs.
• The OpenAPI contract comes from src/lib/openapi/spec.ts.
• Public form runtime behavior comes from the /f/:formKey and /submit handlers.

This public repo should publish artifacts derived from those sources. If this repo and the live product disagree, treat the live product and generated OpenAPI document as authoritative, then fix the stale public resource.

Who This Is For

html.contact is useful when you need:

• A working contact form for a static site, landing page, portfolio, or small business site.
• A real backend for a form generated by Lovable, Bolt, v0, Replit, Cursor, Claude, Codex, or another AI builder.
• A repeatable form backend for client sites, with verified recipients, allowed domains, logs, spam screening, CSV exports, and attachments.
• A scoped Agency API for trusted server-side client, form, and submission workflows (Agency pilot).

It is not trying to be a drag-and-drop survey builder, CRM, payment form platform, or enterprise workflow suite. Bring your own form UI; html.contact handles the backend.

Contributing

This repository is public, but early changes should stay tightly aligned with the app repo. Good contributions improve examples, clarify docs, or make agent instructions safer without changing the public contract by accident.

Before proposing API behavior changes, check the live OpenAPI document at https://html.contact/openapi.json.

Links

• Website: https://html.contact
• Documentation: https://html.contact/docs/
• Examples: https://html.contact/examples/
• OpenAPI: https://html.contact/openapi.json