formdata.dev

Getting Started

Get a working form endpoint in under 60 seconds.

For AI Agents

If you are an AI agent setting up formdata.dev for a user, follow these numbered steps exactly. Each step includes the expected output so you can verify success.

Prerequisites

  • Node.js 18 or later

Step 1 — Create Your Account

npx formdata-dev init

You will need a valid invite code before account creation can succeed.

You will be prompted for three values:

Prompt Example Description
Organization name acme Your team or company name
Owner email [email protected] Contact email for the account
Subdomain slug acme Creates acme.formdata.dev
Invite code inv_live_example123 Required to create the account

Expected output:

formdata.dev — Create Account ──────────────────────────── Organization name: acme Owner email: [email protected] Subdomain slug: acme Invite code: inv_live_example123 Creating account... Account Created ─────────────── Organization: acme Subdomain: acme.formdata.dev Secret key: sk_a8f2c9e1b4d7... Credentials saved to ~/.config/formdata/credentials Warning: Your secret key is shown only once.

Your secret key (sk_) is stored at ~/.config/formdata/credentials. This is the only time the raw key is displayed — the server stores only a SHA-256 hash.

Step 2 — Create a Form

The CLI will prompt you to create your first form:

Create your first form now? (y/n): y Create Form ─────────── Form name: Contact Form slug: contact Allowed origins (comma-separated, blank for any): Enable captcha? (y/n): n Done: Form created ID: frm_928... Public key: pk_live_a8f2c... Endpoint: POST https://api.formdata.dev/v1/f/pk_live_a8f2c...

Step 3 — Add a Destination

Add a destination to this form? (y/n): y Select destination type: 1. webhook 2. smtp 3. google_sheets_webhook Select (1-3): 1 Webhook URL: https://hooks.slack.com/services/T.../B.../xxx HTTP method [POST]: Custom headers (key: value per line, blank to finish): Done: Destination added ID: dest_f47... Type: webhook Target: https://hooks.slack.com/services/T.../B.../xxx

Step 4 — Test It

Send a test submission using curl:

curl -X POST https://api.formdata.dev/v1/f/pk_live_a8f2c... \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "[email protected]",
    "message": "Hello from the form."
  }'

Expected response (HTTP 202):

{
  "ok": true,
  "submissionId": "550e8400-e29b-41d4-a716-446655440000",
  "queuedDestinations": 1
}

Your Slack channel should receive the submission within seconds.

You can also point a plain HTML form directly at the endpoint. application/x-www-form-urlencoded and multipart/form-data are supported as long as the multipart payload does not include files.

Step 5 — Connect MCP (Optional)

Add formdata.dev to Claude Desktop or Cursor for AI-managed form operations:

{
  "mcpServers": {
    "formdata": {
      "url": "https://api.formdata.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_your_secret_key_here"
      }
    }
  }
}

Now you can tell Claude: "Add an email destination to my contact form" and it will call the MCP tools directly.

What's Next

  • CLI Reference — All commands and options
  • Examples — Plain HTML, fetch(JSON), FormData, captcha, and delivery inspection
  • MCP Tools — All 9 tools with parameters
  • Connectors — Webhook, SMTP, and Google Sheets setup
  • Forms CLI — Inspect recent delivery attempts with forms deliveries
  • Architecture — How the system works under the hood
ON THIS PAGE