# html.contact Agent Guide

html.contact gives the app user's coding agents a safe way to add a real form backend to static and AI-generated websites with email notification, spam protection, whitelisted-domain checks, source tracking, logs, and a dashboard.

## Public Snippet

```html
<form action="https://html.contact/f/hc_pub_REPLACE" method="POST">
  <input name="name" placeholder="Your name" required>
  <input name="email" type="email" placeholder="Your email" required>
  <textarea name="message" placeholder="Message" required></textarea>
  <input type="text" name="_gotcha" style="display:none" tabindex="-1" autocomplete="off">
  <div class="cf-turnstile" data-sitekey="TURNSTILE_SITE_KEY"></div>
  <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
  <button type="submit">Send</button>
</form>
```

## Rules

- Read `https://html.contact/design.md` before changing marketing, auth, dashboard, or agent setup UI.
- Read `https://html.contact/viral.md` before changing landing-page messaging.
- Use public `hc_pub_` keys in HTML.
- Never expose private `hc_live_` API keys in frontend code.
- Use `method="POST"`.
- Every input needs a `name`.
- Unknown fields are preserved.
- Unknown underscore fields are preserved.
- Only these reserved behavior fields are supported: `_subject`, `_intro`, `_redirect`, `_replyto`, `_form_name`, `_source`, `_tag`, `_gotcha`, `cf-turnstile-response`, `form_key`.
- Do not use `_to`, `_from`, `_cc`, or `_bcc` for routing.
- Test from the user's whitelisted domain. Direct curl tests should fail unless direct posts are explicitly enabled.

## Private API

Use:

```http
Authorization: Bearer hc_live_xxxxxxxxx
```

See `https://html.contact/openapi.json`.

Design and positioning:

- `https://html.contact/design.md`
- `https://html.contact/viral.md`

If a public form is posted from a non-whitelisted domain, expect `domain_not_allowed`. If it is posted without `Origin` or `Referer`, expect `origin_missing`.

## Setup Codes

Setup codes use the `hc_setup_` prefix and are planned for agent onboarding flows. They are one-time, short-lived, and scoped.

## Future MCP

MCP is planned as a separate Cloudflare Workers/Agents layer using remote MCP over Streamable HTTP and OAuth. It should wrap the private API and require confirmation for destructive actions.