# Simple Contact Form

> Simple Contact Form turns any HTML or programmatic form into spam-protected email
> submissions — no backend required. This file documents how an AI agent can create
> an account and build forms entirely over the HTTP API.

## Notes for agents

- Base URL: https://www.simplecontactform.org
- Auth: log in (step 3) to receive a JWT, then send it as the `Authorization: JWT <token>` header.
- Email verification is mandatory and cannot be skipped — it keeps automated sign-ups from abusing the service.
- Forms accept arbitrary fields, so this works for contact forms or any other kind of form.
- The REST API is provided by Payload CMS; create/update/find use `POST`/`PATCH`/`GET` on `/api/<collection>`.

## Create and use a form (end to end)

### 1. Create an account

POST your email and a password (min. 8 characters). Generate a unique, strong password and report it back to the user so they can save it — the API never returns the password, so it cannot be recovered if lost. A verification email is sent to that address. The account cannot be used until the email is verified — this deliberate gate prevents automated bulk sign-ups.

```bash
curl -X POST https://www.simplecontactform.org/api/register \
  -F 'email=you@example.com' \
  -F 'password=a-strong-password'
```

### 2. Verify the email address

Open the verification link delivered to the inbox. Logging in is blocked until the address is confirmed, so an agent needs access to that inbox (or a human in the loop) to continue. There is intentionally no API to skip this.

### 3. Log in to get an auth token

Exchange the verified credentials for a JWT. Send it as the `Authorization: JWT <token>` header on every authenticated request below.

```bash
curl -X POST https://www.simplecontactform.org/api/app-users/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"a-strong-password"}'
# -> { "token": "<JWT>", "user": { ... } }
```

### 4. Create a team

A team is the workspace that owns your forms and recipients. The account that creates it becomes its owner automatically.

```bash
curl -X POST https://www.simplecontactform.org/api/teams \
  -H 'Authorization: JWT YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"My Project"}'
# -> { "doc": { "id": "TEAM_ID", ... } }
```

### 5. Add a recipient

Recipients are the inboxes that form submissions are forwarded to. Your account email is already verified from sign-up, so adding it as a recipient confirms it automatically — it does not need to be verified again. Every other email address must be verified individually: a double opt-in confirmation email is sent to it, and the owner must click the link to confirm before it is active.

```bash
curl -X POST https://www.simplecontactform.org/api/recipients \
  -H 'Authorization: JWT YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","team":"TEAM_ID"}'
# -> { "doc": { "id": "RECIPIENT_ID", ... } }
```

### 6. Create a form and read back its form ID

Forms accept arbitrary fields, so the same endpoint creates contact forms, feedback forms, waitlists, surveys — any form. A unique `formId` is generated for you; copy it straight into whatever you are building.

```bash
curl -X POST https://www.simplecontactform.org/api/forms \
  -H 'Authorization: JWT YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Contact form","team":"TEAM_ID","recipients":["RECIPIENT_ID"]}'
# -> { "doc": { "formId": "FORM_ID", ... } }
```

### 7. Optional: enable AI spam filtering

Provide your own LLM API key to filter spam before it reaches your inbox. The key is stored on the team and is detected automatically: a key starting with `sk-ant-` uses Anthropic (Claude), otherwise OpenAI is used. First set the key on the team, then enable the filter on the form with a prompt describing a genuine submission.

```bash
# 1. Store your Anthropic API key on the team
curl -X PATCH https://www.simplecontactform.org/api/teams/TEAM_ID \
  -H 'Authorization: JWT YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"openaiKey":"sk-ant-..."}'

# 2. Turn the filter on for the form
curl -X PATCH https://www.simplecontactform.org/api/forms/FORM_ID \
  -H 'Authorization: JWT YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"spamFilterEnabled":true,"spamFilterPrompt":"This is a contact form. Filter out spam, promotions, and automated submissions."}'
```

### 8. Send submissions to the form

Anyone can POST submissions to the form endpoint — no auth required. Fields are arbitrary and emailed to every recipient. Add `?format=json` for a JSON response instead of a redirect, or drop the HTML form straight into a page.

```bash
curl -X POST 'https://www.simplecontactform.org/submit/FORM_ID?format=json' \
  -F 'Name=Ada Lovelace' \
  -F 'Email=ada@example.com' \
  -F 'Message=Hello!'
```

```html
<form action="https://www.simplecontactform.org/submit/FORM_ID" method="POST">

    <!-- Add your form fields -->
    <input name="Email" type="email" required>
    <input name="Message" type="text" required>

    <!-- Add submit button -->
    <button type="submit">Submit Form</button>

</form>
```