# Trazo form intake: integrate a contact form in one call

Trazo (https://gettrazo.app) is a contact-form backend for static websites. A site POSTs its
contact-form data to one public JSON endpoint; Trazo verifies a Cap CAPTCHA token, stores the
submission, classifies it for spam with an AI model, and emails the site's notification address.
No SDK, no email service, no server-side code on your end.

This page covers the public intake endpoint. To manage organizations, sites, submissions, and
users programmatically, see the Management API (https://gettrazo.app/docs/api.md). For AI agent
setup, see https://gettrazo.app/docs/agents.md.

## Keys

- **Site API key** (`sk_live_...`): identifies one site to the intake endpoint. Issued when a
  site is created (in the dashboard or via `POST /api/v1/sites`) and on key rotation. The
  plaintext is shown exactly once; only a hash is stored. It is embedded in public web pages by
  design, and only works from the site's registered domain.
- **Cap site key**: shown on the site's dashboard page (and as `cap_site_key` in the Management
  API). The Cap widget needs it to produce a bot-check token.

No account yet? Sign up at https://gettrazo.app/signup (free tier: 1 site, 1,000 lifetime
submissions) or see https://gettrazo.app/pricing.

## POST https://gettrazo.app/api/v1/submissions

Authenticated by the site key in the body; no `Authorization` header. The page must render the
Cap CAPTCHA widget and send the token it produces. Each Cap token is single-use.

```http
POST https://gettrazo.app/api/v1/submissions
Content-Type: application/json

{
  "api_key": "sk_live_...",
  "cap_token": "<token produced by the Cap widget>",
  "submission": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "message": "I'd like a quote for my project.",
    "custom_fields": { "phone": "555-867-5309" }
  }
}
```

Field rules:

| field | rules |
|---|---|
| `name` | required, max 200 characters |
| `email` | required, valid address, max 255 characters |
| `message` | required, max 5000 characters, newlines preserved |
| `custom_fields` | optional flat object: at most 20 pairs, string keys up to 100 characters, string values up to 1000 characters |

There is no dedicated phone field; put extras in `custom_fields`.

Accepted submissions are stored and emailed to the site's notification address from
`forms@gettrazo.app` after spam classification. The 200 response never waits for that.

## Responses

Every response is JSON. This endpoint keeps its own legacy shape, which differs from the
Management API's error envelope.

| status | body | cause |
|---|---|---|
| 200 | `{ "status": "ok" }` | Stored and queued for delivery. |
| 401 | `{ "status": "error", "message": "Invalid API key" }` | Unknown or rotated key, inactive site or organization, or a lapsed billing cancellation. |
| 403 | `{ "status": "error", "message": "Origin not allowed" }` | The `Origin` header does not match the site's registered domain (`www.` and the bare domain are both accepted). |
| 422 | `{ "status": "error", "message": "Bot verification failed" }` | The Cap token was missing, invalid, or already used. Reset the widget and retry. |
| 422 | `{ "status": "error", "message": "Validation failed", "errors": { "email": ["is invalid"] } }` | A field is missing or malformed; `errors` maps fields to messages. |
| 429 | `{ "status": "error", "message": "Monthly submission limit reached. Try again later." }` | The organization's submission allowance is spent, or IP rate limiting kicked in. |

## Astro template

The fastest start is the https://github.com/gettrazo/astro-template starter, an Astro site with
`ContactForm.astro` already wired to Trazo:

```bash
git clone https://github.com/gettrazo/astro-template my-site
cd my-site
npm install
npm run dev
```

Set `API_KEY` and `CAP_API_ENDPOINT` in `src/config.ts` and the form works on localhost. Keep the
form's `name`, `email`, and `message` field names.

## Plain HTML

No framework needed. Replace the Cap endpoint and the API key with your site's values.

```html
<!-- Cap renders the bot check; Trazo verifies its token server-side -->
<script type="module" src="https://cdn.jsdelivr.net/npm/cap-widget@0.1.56"></script>

<form id="contact-form">
  <input name="name" type="text" required maxlength="200" />
  <input name="email" type="email" required />
  <textarea name="message" required maxlength="5000"></textarea>

  <!-- Replace with your site's Cap endpoint (shown on your site's page) -->
  <cap-widget data-cap-api-endpoint="https://cap.gettrazo.app/YOUR_CAP_SITE_KEY/"></cap-widget>

  <button type="submit">Send</button>
  <p id="contact-status" hidden></p>
</form>

<script>
  const form = document.getElementById("contact-form");
  const status = document.getElementById("contact-status");

  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    status.hidden = true;

    const res = await fetch("https://gettrazo.app/api/v1/submissions", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        api_key: "sk_live_your_api_key_here",
        cap_token: form.querySelector('[name="cap-token"]')?.value,
        submission: {
          name: form.name.value,
          email: form.email.value,
          message: form.message.value,
        },
      }),
    });

    const data = await res.json();
    status.hidden = false;
    if (data.status === "ok") {
      status.textContent = "Thanks! Your message is on its way.";
      form.reset();
    } else {
      status.textContent = data.message || "Something went wrong. Please try again.";
      document.querySelector("cap-widget")?.reset();
    }
  });
</script>
```
