JavaScript

The form keeps its action and method, so it posts on its own until the script runs. The same request carries files, a spam blocker token and validation errors, and Axios or XMLHttpRequest can send it for code that uses them.

Prerequisites

Before you start, you need:

A formcarry account. Sign up is free.
A form in the dashboard. Its endpoint is on the form’s Setup page. The examples use https://formcarry.com/s/AbC123xyz; put yours in its place.

Fetch

To send a form with fetch, keep action and method="POST" on the form, post a FormData built from it on submit, and send Accept: application/json:

<form id="contact" action="https://formcarry.com/s/AbC123xyz" method="POST">
  <input type="email" name="email" placeholder="Email">
  <textarea name="message" placeholder="Message"></textarea>
  <button type="submit">Send</button>
  <p id="result"></p>
</form>

<script>
  const form = document.getElementById("contact")
  const result = document.getElementById("result")

  form.addEventListener("submit", async (e) => {
    e.preventDefault()
    const res = await fetch(form.action, {
      method: "POST",
      headers: { "Accept": "application/json" },
      body: new FormData(form),
    })
    const data = await res.json()
    result.textContent = data.message
  })
</script>

Until the script has run, the browser posts the form itself and the visitor lands on the thank you page. After that, the answer is JSON. The email field is the visitor’s address, so it becomes the reply to address of your notification email and the recipient of the auto response. A stored submission answers with code: 200. A refused one answers with the reason in message, see What every form needs. Send Accept: application/json rather than leaving it out, otherwise the answer is the thank you page’s HTML and res.json() throws. To refuse a second click before the answer arrives, disable the submit button and enable it again after:

const button = form.querySelector("button[type=submit]")

form.addEventListener("submit", async (e) => {
  e.preventDefault()
  button.disabled = true
  try {
    const res = await fetch(form.action, {
      method: "POST",
      headers: { "Accept": "application/json" },
      body: new FormData(form),
    })
    const data = await res.json()
    result.textContent = data.message
  } catch {
    result.textContent = "No answer from formcarry. Send again."
  } finally {
    button.disabled = false
  }
})

A second submission within 15 seconds from the same address gets a 429, so the button stays disabled until the answer is in. fetch rejects only when no answer came back; a refused submission resolves, with the reason in data.message. To post an object instead, send it as JSON with Content-Type: application/json:

const fields = { email: form.elements.email.value, message: form.elements.message.value }

const res = await fetch(form.action, {
  method: "POST",
  headers: { "Accept": "application/json", "Content-Type": "application/json" },
  body: JSON.stringify(fields),
})

The keys are the field names formcarry stores.

Files

To send files, add file inputs to the form from the first example and keep the FormData post:

<input type="file" name="attachment">
<input type="file" name="photos" accept=".jpg, .png" multiple>

The script does not change. A multiple input sends every chosen file under its name. For File objects from elsewhere, append each one under its own name:

const data = new FormData(form)
files.forEach((file, i) => data.append(`file-${i}`, file, file.name))

Leave Content-Type to the browser rather than setting it, otherwise the multipart boundary is missing and the upload fails. For small files, stay with JSON and send each file as a data URL, one key per file, never an array:

const toDataUrl = (file) =>
  new Promise((resolve, reject) => {
    const reader = new FileReader()
    reader.onload = () => resolve(reader.result)
    reader.onerror = reject
    reader.readAsDataURL(file)
  })

const attachment = await toDataUrl(form.elements.attachment.files[0])

body: JSON.stringify({ ...fields, attachment }),

Use data URLs for small files. Using them with larger files bloats the request by about a third and reaches the 50 MB limit sooner.

Files are stored on paid plans only. Free plans store the rest of the submission without them.

Spam blocker

To add a challenge, load its script, put a div with the widget class and your site key inside the form, and paste the secret key into the form’s settings under Form Security:

Challenge	Script	Widget class	Token field
reCAPTCHA v2	`https://www.google.com/recaptcha/api.js`	`g-recaptcha`	`g-recaptcha-response`
reCAPTCHA v3	`https://www.google.com/recaptcha/api.js?render=SITE_KEY`	none	`g-recaptcha-response`
hCaptcha	`https://js.hcaptcha.com/1/api.js`	`h-captcha`	`h-captcha-response`
Turnstile	`https://challenges.cloudflare.com/turnstile/v0/api.js`	`cf-turnstile`	`cf-turnstile-response`

With reCAPTCHA v2:

<script src="https://www.google.com/recaptcha/api.js" async defer></script>

<!-- inside the form, before the submit button -->
<div class="g-recaptcha" data-sitekey="SITE_KEY"></div>

The reCAPTCHA v2, hCaptcha and Turnstile widgets each add a field named after their token to the form, so the FormData post above carries it. With reCAPTCHA v3 there is no widget. Load the script with your site key, add a hidden input for the token, and ask for a token when the visitor submits:

<script src="https://www.google.com/recaptcha/api.js?render=SITE_KEY"></script>

<!-- inside the form -->
<input type="hidden" name="g-recaptcha-response">

<script>
  form.addEventListener("submit", (e) => {
    e.preventDefault()
    grecaptcha.ready(() => {
      grecaptcha.execute("SITE_KEY", { action: "submit" }).then(async (token) => {
        form.elements["g-recaptcha-response"].value = token
        const res = await fetch(form.action, {
          method: "POST",
          headers: { "Accept": "application/json" },
          body: new FormData(form),
        })
        const data = await res.json()
        result.textContent = data.message
      })
    })
  })
</script>

With a JSON post, read the token and add it by hand:

body: JSON.stringify({ ...fields, "g-recaptcha-response": form.elements["g-recaptcha-response"].value }),

Refuse to send while the token is empty rather than posting anyway, otherwise formcarry answers 403 for reCAPTCHA or 400 for the others:

if (!form.elements["g-recaptcha-response"].value) {
  result.textContent = "Complete the challenge first."
  return
}

Add localhost to the challenge’s allowed domains while you test.

Validation errors

A 422 carries errors, one entry per failing field, each with a message. To mark each failing field invalid and let the browser report it:

if (data.code === 422) {
  for (const name in data.errors) {
    const field = form.elements[name]
    field.setCustomValidity(data.errors[name].message)
    field.addEventListener("input", () => field.setCustomValidity(""), { once: true })
  }
  form.reportValidity()
}

The browser shows each message next to its field in its own style. Clear the custom validity on the next input rather than leaving it set, otherwise the browser refuses to submit the form again. To show each message in your own markup instead, mark the field and add a span after it:

if (data.code === 422) {
  for (const name in data.errors) {
    const field = form.elements[name]
    field.classList.add("fc-field-error")
    const note = document.createElement("span")
    note.className = "fc-field-error-message"
    note.textContent = data.errors[name].message
    field.after(note)
  }
}

Remove the class and the spans before the next post rather than leaving them, otherwise old messages stay next to fields that now pass.

Axios

The same post with Axios from its CDN script, with form and result from the first example:

<script src="https://cdn.jsdelivr.net/npm/axios@1/dist/axios.min.js"></script>
<script>
  form.addEventListener("submit", async (e) => {
    e.preventDefault()
    try {
      const { data } = await axios.post(form.action, new FormData(form), {
        headers: { Accept: "application/json" },
      })
      result.textContent = data.message
    } catch (err) {
      result.textContent = err.response ? err.response.data.message : "No answer from formcarry. Send again."
    }
  })
</script>

Leave Content-Type to Axios rather than setting it, otherwise the FormData upload loses its boundary. Axios rejects on any status outside 2xx, so formcarry’s answer to a refused submission is in err.response.data. A request that got no answer has no response, so check for it before reading it. To post an object instead, pass it in place of the FormData; Axios sends it as JSON:

const { data } = await axios.post(form.action, fields, {
  headers: { Accept: "application/json" },
})

XMLHttpRequest

For code that cannot use fetch, the same post with XMLHttpRequest:

var xhr = new XMLHttpRequest()
xhr.open("POST", "https://formcarry.com/s/AbC123xyz")
xhr.setRequestHeader("Accept", "application/json")
xhr.onload = function () {
  var data = JSON.parse(xhr.responseText)
  result.textContent = data.message
}
xhr.onerror = function () {
  result.textContent = "No answer from formcarry. Send again."
}
xhr.send(new FormData(form))

onload runs for 422 and 403 too, so read data.code. onerror runs only when no answer came back. For a JSON body, set Content-Type and send a string:

xhr.setRequestHeader("Content-Type", "application/json")
xhr.send(JSON.stringify(fields))

What’s next

Field validations: the rules you can set per field.
Spam protection: the challenges, the filter and the honeypot.
Email notifications: the auto response the visitor gets, keyed on email.

Stuck? Write to help@formcarry.com. Include the form id.

Getting Started

Features

Email Configuration

Integrations

Frameworks

Site builders

Build with AI

Connect over MCP

Prerequisites

Fetch

Files

Spam blocker

Validation errors

Axios

XMLHttpRequest

What’s next

​Prerequisites

​Fetch

​Files

​Spam blocker

​Validation errors

​Axios

​XMLHttpRequest

​What’s next

Prerequisites

Fetch

Files

Spam blocker

Validation errors

Axios

XMLHttpRequest

What’s next