# formcarry

> formcarry is one inbox for every form you run. A form posts its fields to its endpoint, `https://formcarry.com/s/{form_id}`, and formcarry stores the submission, emails it to the owner, filters spam and passes it on to webhooks, Zapier and the API. Any HTML page, React, Next.js, Vue or Svelte app, a Webflow, Framer, WordPress, Wix or Squarespace site, or a site an AI tool built can send to it. Accounts: https://app.formcarry.com/register. The endpoint is on the form's Setup page in the dashboard, https://app.formcarry.com.

## How to connect a form

Read this section before writing any code. It is the whole contract.

- Send a `POST` to the endpoint. A `GET` is answered with a page that says GET is not allowed.
- Accepted bodies: `application/x-www-form-urlencoded` (a plain HTML form), `multipart/form-data` (files), `application/json` (JavaScript). Up to 50 MB per request.
- Every field needs a `name`. formcarry stores the value under that name, as sent.
- Name the visitor's address field `email`. It becomes the reply to address of the owner's notification email and the recipient of the auto response.
- Reserved names, read and not stored: `_gotcha` (honeypot, leave it empty), `_next` (a redirect URL for one submission, paid plans, used only when the form's thank you URL in the dashboard is empty), `submit`, and the challenge tokens `g-recaptcha-response`, `h-captcha-response`, `cf-turnstile-response`.
- From JavaScript, send `Accept: application/json`. The answer is JSON with `code`, `status`, `title` and `message`, and the HTTP status equals `code`. Stored: `{"code":200,"status":"success","title":"Thank You!","message":"We received your submission"}`. `422`: a validation rule failed, `errors` holds one entry per failing field with a `message`. `403`: no fields, or the reCAPTCHA token was rejected. `400`: the hCaptcha or Turnstile token was rejected. `429`: a second submission within 15 seconds from the same IP address for the same form. `401`: wrong form id or a paused form.
- Without the `Accept` header the browser lands on formcarry's thank you page, or on the form's thank you URL when one is set in the dashboard.
- Files: send `multipart/form-data` (a `FormData` in JavaScript); a field can carry several files, each appended under its own name. From JSON, a data URL string is stored as a file, one key per file, never an array. Leave `Content-Type` to the browser when sending `FormData`. Files are stored on paid plans; the free plan stores the rest of the submission without them.
- Spam blocker: render reCAPTCHA, hCaptcha or Turnstile in the page and send its token under the field name above. The secret key goes into the form's settings under Form Security. Never post with an empty token.
- Post from the browser, not from a server. From a server every visitor shares one IP address against the 15 second limit, and no challenge token exists.

A plain HTML form:

```html
<form action="https://formcarry.com/s/{form_id}" method="POST">
  <input type="email" name="email">
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>
```

The same from JavaScript:

```js
const res = await fetch("https://formcarry.com/s/{form_id}", {
  method: "POST",
  headers: { "Accept": "application/json", "Content-Type": "application/json" },
  body: JSON.stringify({ email, message }),
})
const data = await res.json() // data.code === 200 when stored, data.message says why otherwise
```

## Setup by stack

- [Quickstart](https://formcarry.com/docs/quickstart): a plain HTML form in three steps.
- [What every form needs](https://formcarry.com/docs/what-every-form-needs): field names, hidden inputs, files, limits and every answer the endpoint gives.
- [How formcarry works](https://formcarry.com/docs/how-it-works): storage first, deliveries tried until delivered, security and GDPR.
- [React](https://formcarry.com/docs/frameworks/react), [Next.js](https://formcarry.com/docs/frameworks/nextjs), [Vue](https://formcarry.com/docs/frameworks/vue), [Svelte](https://formcarry.com/docs/frameworks/svelte), [JavaScript](https://formcarry.com/docs/frameworks/javascript), [jQuery](https://formcarry.com/docs/frameworks/jquery), [formcarry.js](https://formcarry.com/docs/frameworks/formcarry-js): one page per framework, each with files, spam blockers and validation errors.
- [Webflow](https://formcarry.com/docs/builders/webflow), [Framer](https://formcarry.com/docs/builders/framer), [WordPress](https://formcarry.com/docs/builders/wordpress), [Wix](https://formcarry.com/docs/builders/wix), [Squarespace](https://formcarry.com/docs/builders/squarespace): the builder's own settings, step by step.

## Manage forms and submissions from code or from an AI tool

- API: `https://api.formcarry.com/v1`, authenticated with `Authorization: Bearer fc_live_...` from the dashboard's API Keys page, 10 requests per second per key. Reference: https://api.formcarry.com/docs. Create and configure forms, list and filter submissions, manage recipients and webhooks.
- MCP server: `https://mcp.formcarry.com/mcp`. Claude, Codex, Cursor and v0 connect to it with OAuth and can create forms, change their settings and read submissions from the chat. Setup steps per tool: https://app.formcarry.com/connect.

## Support

Write to help@formcarry.com with the form id.