# Etariosk Form

> Turn any HTML form into an email inbox. POST form data to an Etariosk Form
> endpoint and the submission arrives as email - no backend, no SMTP,
> no server code to write or host.

This file is for AI coding agents (Claude Code, Cursor, Copilot, ChatGPT,
etc.) wiring Etariosk Form into a project. Follow it exactly - don't invent
endpoints, headers, or field names that aren't listed here.

## What you need before you start

Etariosk Form requires a human-owned account - an agent can't create one.
Ask the person you're working with for:

1. Their endpoint: `https://forms.etariosk.com/f/<form-id>`
2. Their API key: `ef_live_...`

Both are on their dashboard at https://forms.etariosk.com/dashboard
once they sign in with Google and get approved (usually within a day).
If they haven't done that yet, tell them to and pause - don't fabricate
placeholder values that look real; use `<your-endpoint>` and
`<your-api-key>` as visible placeholders instead.

## Integrating into an EXISTING form

1. Find the form's `<form>` tag.
2. Set `action` to the endpoint and `method` to `POST`. Leave `enctype`
   alone - Etariosk Form accepts `application/x-www-form-urlencoded`,
   `multipart/form-data`, and `application/json` bodies.
3. Add a hidden field carrying the API key. Don't remove or rename any
   of the form's existing fields:
   `<input type="hidden" name="_key" value="<your-api-key>">`
4. Leave field names as they are. Etariosk Form looks for
   `email`/`from`/`from_email`/`reply_to` to set the email's Reply-To,
   and `message`/`body`/`comment`/`comments`/`text` for the preview -
   but it stores and forwards every field regardless of name.
5. If the form already submits via `fetch`/XHR instead of a native POST,
   keep that pattern. Just point the request at the endpoint and either
   add `_key` to the body or send `Authorization: Bearer <your-api-key>`
   as a header instead, if you'd rather keep the key out of the DOM.

## Building a NEW form

Minimal working example:

```html
<form action="<your-endpoint>" method="POST">
  <input name="email" type="email" required>
  <textarea name="message" required></textarea>
  <input type="hidden" name="_key" value="<your-api-key>">
  <button type="submit">Send</button>
</form>
```

Fetch/JSON equivalent (React/Vue/etc. component):

```js
await fetch("<your-endpoint>", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <your-api-key>",
  },
  body: JSON.stringify({ email, message }),
})
```

## Reserved fields - don't reuse these names for your own data

- `_key` - API key, if not sent as an `Authorization: Bearer` header instead.
- `_subject` - overrides the delivered email's subject line.
- `_redirect` - absolute URL to send the visitor to after a successful POST.
- `_honey` - honeypot. Render this input empty and hidden from real users
  (e.g. `position:absolute; left:-9999px`, `tabindex="-1"`,
  `autocomplete="off"` - don't use `display:none`, some spam bots skip
  those). Bots that fill every field trip it; the submission is silently
  flagged as spam with no error shown to them.

## Responses

- `200 OK`, JSON `{ "ok": true, "id": "<submission-id>" }` - accepted. A native
  form POST doesn't need to handle this itself.
- `303 See Other` - sent instead of 200 when `_redirect` was set; the
  browser follows it automatically for a native form POST.
- `401` - API key missing, wrong, or rotated. Don't retry with a guessed key.
- `403` - the request's Origin isn't on the form's allowed-origins list
  (only enforced if the account owner configured one; unset = any origin).
- `404` - bad form id, or the form has been retired.

There is no `429`. Every submission is stored, so nothing is lost even if the
account is over its monthly email quota - only the forwarding email pauses.

## Things not to do

- Don't invent a different endpoint shape - it's exactly `/f/<form-id>`,
  no `/api/`, `/submit`, or `/v1/` prefix.
- Don't add your own spam/CAPTCHA layer unless asked - `_honey` is the
  provided mechanism.
- Don't send the API key as a URL query parameter.
- Don't build a server-side proxy for this. The point of Etariosk Form is that
  no backend is needed - POST directly from the browser.

## More

Human-facing docs (live example with the account's real endpoint/key):
https://forms.etariosk.com/docs