Documentation

Getting started

1. Create a free account.
2. Add a recipient: give it a name and the destination email that should receive submissions. A key is generated instantly, nothing is required from that inbox's owner.
3. Copy one of the snippets below into your site's contact form, using the key shown on that recipient's Overview page.
4. Optionally lock the key to your site's domain under Origin locking.
5. Test-submit the live form, then check the recipient's Submissions log for a “delivered” entry.

Embed snippet

Every recipient has its own key and ready-made snippets on its Overview page in the dashboard. The examples below show the same two variants with a placeholder key.

Plain HTML form

<form action="https://app.formgopher.com/api/submit" method="POST">
  <input type="hidden" name="access_key" value="fg_live_your_key_here">
  <input type="text" name="name" placeholder="Your Name" required>
  <input type="email" name="email" placeholder="Your Email" required>
  <textarea name="message" placeholder="Your Message" required></textarea>
  <input type="checkbox" name="_honeypot" style="display:none" tabindex="-1" autocomplete="off">
  <!-- Optional: send visitors to your own page after they submit -->
  <!-- <input type="hidden" name="redirect" value="https://yoursite.com/thanks"> -->
  <button type="submit">Send</button>
</form>

fetch() form

<form id="contact-form">
  <input type="text" name="name" placeholder="Your Name" required>
  <input type="email" name="email" placeholder="Your Email" required>
  <textarea name="message" placeholder="Your Message" required></textarea>
  <input type="checkbox" name="_honeypot" style="display:none" tabindex="-1" autocomplete="off">
  <button type="submit">Send</button>
</form>
<script>
  document.getElementById('contact-form').addEventListener('submit', async function (e) {
    e.preventDefault()
    const form = e.target
    const button = form.querySelector('button[type="submit"]')
    const originalLabel = button.textContent
    button.disabled = true
    button.textContent = 'Sending…'
    try {
      const formData = new FormData(form)
      formData.append('access_key', 'fg_live_your_key_here')
      const response = await fetch('https://app.formgopher.com/api/submit', {
        method: 'POST',
        body: formData,
      })
      if (response.ok) {
        alert('Message sent!')
        form.reset()
      } else {
        const result = await response.json().catch(function () { return null })
        alert((result && result.error) || 'Something went wrong. Please try again.')
      }
    } catch {
      alert('Something went wrong. Please check your connection and try again.')
    } finally {
      button.disabled = false
      button.textContent = originalLabel
    }
  })
</script>

File attachments (Warren plan)

Warren-tier recipients can accept file uploads with a submission, like resumes, signed documents, or reference photos, sent straight through with the notification email.

Limits (Warren plan)

If a submission exceeds either limit, the excess files, in the order they were selected, are stripped the same way as on the Free plan; the rest of the submission still delivers normally. Since files can be silently dropped this way, consider adding a client-side check (file count, running total size) before submit so visitors get instant feedback instead of finding out later that a file didn't arrive.

Sending files

A plain HTML form needs enctype="multipart/form-data" on the <form> tag itself; a type="file" input on its own isn't enough to switch the encoding. Building the fetch() variant instead? Submit a FormData object as the body and don't set a Content-Type header yourself; the browser sets the multipart boundary for you.

The name on a file input doesn't matter to Formgopher, any file part in the request is accepted regardless of field name. Add the multiple attribute to let a visitor attach more than one file from a single input. Whatever file input(s) you use must sit inside the <form> element, carry a name attribute (browsers omit unnamed controls when building the submission), and not be disabled at submit time.

Plain HTML form

<form action="https://app.formgopher.com/api/submit" method="POST" enctype="multipart/form-data">
  <input type="hidden" name="access_key" value="fg_live_your_key_here">
  <input type="text" name="name" placeholder="Your Name" required>
  <input type="email" name="email" placeholder="Your Email" required>
  <textarea name="message" placeholder="Your Message" required></textarea>
  <input type="file" name="attachments" multiple>
  <input type="checkbox" name="_honeypot" style="display:none" tabindex="-1" autocomplete="off">
  <button type="submit">Send</button>
</form>

fetch() form

<form id="contact-form">
  <input type="text" name="name" placeholder="Your Name" required>
  <input type="email" name="email" placeholder="Your Email" required>
  <textarea name="message" placeholder="Your Message" required></textarea>
  <input type="file" name="attachments" multiple>
  <input type="checkbox" name="_honeypot" style="display:none" tabindex="-1" autocomplete="off">
  <button type="submit">Send</button>
</form>
<script>
  document.getElementById('contact-form').addEventListener('submit', async function (e) {
    e.preventDefault()
    const form = e.target
    const button = form.querySelector('button[type="submit"]')
    const originalLabel = button.textContent
    button.disabled = true
    button.textContent = 'Sending…'
    try {
      const formData = new FormData(form)
      formData.append('access_key', 'fg_live_your_key_here')
      const response = await fetch('https://app.formgopher.com/api/submit', {
        method: 'POST',
        body: formData,
      })
      if (response.ok) {
        alert('Message sent!')
        form.reset()
      } else {
        const result = await response.json().catch(function () { return null })
        alert((result && result.error) || 'Something went wrong. Please try again.')
      }
    } catch {
      alert('Something went wrong. Please check your connection and try again.')
    } finally {
      button.disabled = false
      button.textContent = originalLabel
    }
  })
</script>

Delivered attachments stay downloadable from the dashboard's File Manager for 90 days after submission, then are automatically deleted.

CC emails (Warren plan)

Forward a recipient's notification email to up to 4 extra addresses at the same time as the main inbox, handy for looping in an assistant or a shared team inbox without setting up a separate recipient for them. Add CC addresses from that recipient's settings in the dashboard; it's a per-recipient setting, so turning it on for one client's site doesn't change how any other recipient on the account behaves. Every CC address gets the exact same notification email as the primary recipient, reply-to and all, so anyone on the list can reply straight to the visitor too.

API reference

Accepts application/json, application/x-www-form-urlencoded, or multipart/form-data (required only when attaching files; see File attachments).

Fields

Response

{
  "success": true
}

{
  "success": false,
  "error": "Origin not allowed for this key"
}

A plain HTML form POST (no JavaScript) instead receives an HTML redirect to your redirect URL, or a built-in “message sent” page, rather than JSON.

Error codes

Submissions API (Warren plan)

Pull your own recipients' submissions into a tool you control, like a client portal, an internal dashboard, or a CRM, instead of only viewing them in the Formgopher dashboard. Read-only, and available on the Warren plan.

Get your API key

1. Go to Settings in the Formgopher dashboard.
2. Find the Submissions API section.
3. Click Generate API key.
4. Copy the key immediately: it's shown once, and Formgopher never stores the plaintext. If you lose it, generate a new one; this immediately invalidates the old one.

Make a request

GET https://app.formgopher.com/api/submissions?access_key=YOUR_RECIPIENT_ACCESS_KEY
Authorization: Bearer YOUR_SECRET_API_KEY

Query parameters

This endpoint only works as a server-to-server call (no browser CORS support, by design), so call it from your own backend rather than directly from a webpage's JavaScript.

Read the response

{
  "success": true,
  "recipient": { "id": "...", "name": "Rosa's Bakery" },
  "submissions": [
    {
      "id": "...",
      "originDomain": "rosasbakery.com",
      "fields": { "name": "Jane Doe", "email": "jane@example.com", "message": "..." },
      "status": "delivered",
      "failureReason": null,
      "flagged": false,
      "flagReasons": [],
      "confirmationStatus": null,
      "attachments": [
        { "filename": "photo.jpg", "size": 204800, "included": true, "reason": null, "downloadUrl": "https://..." }
      ],
      "sentAt": "2026-09-20T14:32:00.000Z"
    }
  ],
  "nextCursor": null
}

• fields mirrors whatever your contact form actually submits; there's no fixed schema.
• status is delivered, failed, or blocked.
• attachments[].downloadUrl, when present, is valid for about 15 minutes. Fetch a fresh one by calling the endpoint again rather than storing it.
• Results are newest first. nextCursor is null when there are no more pages.

Error codes

Managing your key

Back in Settings → Submissions API, you can:

• Regenerate: issues a new key and immediately invalidates the old one.
• Revoke: turns off API access entirely until you generate a new key.

Available on the Warren plan only; on Free, this section of Settings shows an upgrade prompt instead.

Spam protection (Warren plan)

Warren-tier recipients get a lightweight spam check on every submission, looking at things like suspicious links, spam-like keywords, and bursts of submissions from the same visitor. Per recipient, you choose whether flagged submissions still get delivered and are just tagged in the log (“flag”, the default), or are dropped before ever being sent (“block”). Free-tier recipients skip this check entirely.

Auto-confirmation emails (Warren plan)

Warren-tier recipients can send a second email straight back to the visitor confirming their message got through, so they get an immediate “we got it” instead of silence while they wait on a reply.

Enabling it

Auto-confirmation is off by default and toggled per recipient, from that recipient's settings in the dashboard. Turning it on for one recipient doesn't touch any others on the account, so you can enable it for one client's site without changing how the rest of your forms behave.

Subject & message

Both fields are optional. Leave either blank and Formgopher fills in a default:

If a submission gets flagged by spam protection, the confirmation email is skipped, even though the primary notification to the recipient still goes through as normal, keeping Formgopher's sending reputation clean by not emailing addresses likely to belong to a bot. The recipient's Submissions log shows whether each confirmation sent successfully or bounced, which doubles as a handy signal that a visitor may have mistyped their own email address.

Auto-confirmation is a distinct, Formgopher-generated email, not a relay of the recipient's own autoresponder or out-of-office reply; that would require inbound email infrastructure Formgopher doesn't have. A fixed, editable confirmation keeps the feature simple and fully within Formgopher's control.

Origin locking

By default, a key works from any site that submits to it. Adding one or more domains to a recipient's allowed origins restricts it to only accept submissions whose request origin matches, useful once a client's site is live. This is a separate, optional step from creating the recipient, so you can generate a key before a site even has a domain.

Plans & limits