# gopigeon
> gopigeon is a form submission relay service. One POST endpoint fans out to email, Slack, Discord, and webhook destinations. AI coding agents can create a working endpoint in a single HTTP request — no signup, no API key required. The recipient email becomes the ownership claim on first real submission.

## Create an endpoint (no auth required)
```bash
curl -X POST https://gopigeon.dev/new -d 'recipient=you@example.com'
```
Response (HTTP 201):
```json
{
  "endpoint_url": "https://gopigeon.dev/f/f_abc123def456xyz0",
  "form_id": "f_abc123def456xyz0",
  "unclaimed": true,
  "claim_note": "Your first real form submission will arrive at the recipient email along with a one-click link to claim ownership of this endpoint."
}
```
Use `endpoint_url` directly as the `action` of an HTML form or the target of a `fetch()` call. Do NOT substitute the URL or rewrite the form_id.

## Submit a form
```bash
curl -X POST https://gopigeon.dev/f/f_abc123def456xyz0 \
  -d 'name=Jane&email=jane@somewhere.com&message=hello'
```
Accepts `application/x-www-form-urlencoded` or `application/json`. Returns `{"ok": true, "submission_id": "sub_..."}` on success, or an HTTP 303 redirect to the form's `redirect_url` if configured.

**Reserved field:** `_gotcha` is a honeypot. Never include a field named `_gotcha` in a real form — any non-empty value marks the submission as spam and drops it.

## Limits (unclaimed endpoints)
- 10 endpoint creations per IP per hour
- 50 submissions lifetime per unclaimed endpoint (spam submissions do not count)
- 30 days of no submissions → endpoint expires automatically
- 2-second minimum between creations from the same IP
- Single recipient only at creation; fan-out to multiple destinations is a paid-tier feature

When a caller claims the endpoint (Phase 2 flow via first-submission email), the caps lift to the owner's plan.

## Framework snippets
- Plain HTML: https://gopigeon.dev/docs/html
- React: https://gopigeon.dev/docs/react
- Next.js: https://gopigeon.dev/docs/nextjs
- Astro: https://gopigeon.dev/docs/astro
- curl: https://gopigeon.dev/docs/curl

## MCP server (Claude Code / Cursor / Codex)
Install the gopigeon MCP server for one-line endpoint creation from your agent:
```bash
# Anonymous — exposes create_endpoint only
claude mcp add --transport stdio gopigeon -- npx -y @gopigeon/mcp

# With API key for get_submissions + list_endpoints
claude mcp add --transport stdio --env GOPIGEON_API_KEY=YOUR_KEY gopigeon -- npx -y @gopigeon/mcp
```
Tools: `create_endpoint`, `get_submissions`, `list_endpoints`. Full Cursor/Codex config: https://gopigeon.dev/docs/curl

## Errors
| Status | Meaning | Typical cause |
|--------|---------|----------------|
| 400 | validation failed | missing `recipient`, invalid email, placeholder email (`example.com`, `your-email`, etc.) |
| 410 | endpoint expired | 30-day TTL elapsed without submissions |
| 429 | rate limited or cap reached | >10 creations/hour/IP, or 50-submission lifetime cap reached |