An HTML form without a backend: plain HTML, Astro and Next.js
You can run an HTML form without a backend by posting it to a hosted form endpoint. The endpoint receives the submission, stores it, emails it to you and sends the visitor on to your thank-you page. With SagePigeon that endpoint is a URL on your form's Setup tab, and the only change to your page is the form's action plus one hidden field. Below are working versions for plain HTML, Astro and Next.js, and what the endpoint sends back in each case.
How a form without a backend works
A static site has nowhere to run code when someone presses Send. So the form posts somewhere else. SagePigeon's endpoint looks like https://api.example.com/f/FORM_ID; yours is printed on the form's Setup tab, already inside each snippet.
When a submission arrives, SagePigeon checks it against the form's rules (required fields, spam trap, rate limit, allowed sites), writes it to your workspace, and only then queues the emails and integrations. A bounced email or a Slack outage cannot lose a request that is already stored.
The endpoint then answers the browser. A normal form post gets a 303 redirect to your thank-you page once you have set one. Until you do, the visitor sees a short SagePigeon page that says "Sent. Thank you." A request that asks for JSON gets JSON.
Plain HTML
This is the snippet from the Setup tab:
<form action="https://api.example.com/f/FORM_ID" method="POST">
<input name="name" placeholder="Name" required />
<input name="email" type="email" placeholder="Email" required />
<textarea name="message"></textarea>
<input name="_gotcha" type="text" tabindex="-1" hidden autocomplete="off" />
<button type="submit">Send</button>
</form>Each name becomes a field in the submission. Use the same names in your email template and they will line up.
Keep the _gotcha input. Bots fill in every field they find, people never see this one, and anything that arrives with it filled is filed as spam while the bot is told it succeeded.
Then set the redirect. Open the form's Settings tab and put your thank-you page in Redirect after submit, under Delivery. Skip it and a visitor who submits a plain form gets SagePigeon's page instead. It says "Sent. Thank you." and "Your message has been sent.", but it carries none of your branding.
Staying on the page with formsage.js
If you would rather keep the visitor on the page, add SagePigeon's script and mark the form with data-formsage:
<script src="https://app.example.com/formsage.js" defer></script>
<form action="https://api.example.com/f/FORM_ID" method="POST" data-formsage>
<input name="email" type="email" required />
<textarea name="message"></textarea>
<input name="_gotcha" type="text" tabindex="-1" hidden autocomplete="off" />
<button>Send</button>
</form>Copy the exact script line from the JavaScript snippet on your Setup tab. The script has no dependencies and needs no build step. It submits with fetch, replaces the form with a thank-you message when it succeeds (or follows your redirect if you set one), and shows an inline error when it does not. The formsage:success and formsage:error events let you take over either of those; the events docs show both.
It also reports submissions that never reached SagePigeon, which a plain form cannot do. If the request times out after 15 seconds, is blocked by your page's Content-Security-Policy, or fails because the visitor went offline, the form's Health tab shows it as "Failed in the browser". The report carries the kind of failure and the page's path, and never a field value.
Astro
Astro outputs plain HTML, so the snippet works unchanged in a .astro file. Use is:inline so Astro leaves the external script alone:
---
const endpoint = 'https://api.example.com/f/FORM_ID'
---
<form action={endpoint} method="POST" data-formsage>
<label>Email <input name="email" type="email" required /></label>
<label>Message <textarea name="message"></textarea></label>
<input name="_gotcha" type="text" tabindex="-1" hidden autocomplete="off" />
<button>Send</button>
</form>
<script is:inline src="https://app.example.com/formsage.js" defer></script>This works with a fully static build. No adapter, no server endpoint.
Next.js
In Next.js you do not need an API route or a server action to collect a form. A client component can post straight to the endpoint. Send JSON, so SagePigeon answers with JSON:
'use client'
import { useState, type FormEvent } from 'react'
const ENDPOINT = 'https://api.example.com/f/FORM_ID'
export default function ContactForm() {
const [status, setStatus] = useState<'idle' | 'sending' | 'sent' | 'failed'>('idle')
const [error, setError] = useState('')
async function onSubmit(event: FormEvent<HTMLFormElement>) {
event.preventDefault()
setStatus('sending')
const fields = Object.fromEntries(new FormData(event.currentTarget))
const res = await fetch(ENDPOINT, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(fields),
})
const body = await res.json().catch(() => ({}))
if (res.ok) return setStatus('sent')
setStatus('failed')
setError(body.message ?? 'That did not go through. Please try again.')
}
if (status === 'sent') return <p>Thanks. We will reply by email.</p>
return (
<form onSubmit={onSubmit}>
<input name="email" type="email" required />
<textarea name="message" />
<input name="_gotcha" type="text" tabIndex={-1} hidden autoComplete="off" />
<button disabled={status === 'sending'}>Send</button>
{status === 'failed' && <p role="alert">{error}</p>}
</form>
)
}Note JSON.stringify on the fields. Passing new FormData(form) as the body sends multipart data, which SagePigeon does not read as fields. JSON and URL-encoded bodies both work, as the Posting JSON docs explain.
What the endpoint answers
| Status | Body | Means |
|---|---|---|
| 200 | { "ok": true, "submissionId": "…" } | Stored and queued for delivery |
| 303 | (redirect) | Plain form post, sent to your thank-you page |
| 200 | (a short HTML page) | Plain form post with no thank-you page set |
| 422 | { "error": "missing_fields", "fields": ["email"] } | A required field was empty |
| 403 | { "error": "origin_not_allowed" } | Posted from a site not on the allowlist |
| 403 | { "error": "captcha_failed" } | A Turnstile or reCAPTCHA token was missing or invalid |
| 413 | { "error": "payload_too_large" } | The body was over 256 KB |
| 429 | { "error": "rate_limited" } | Too many posts from one address |
| 402 | { "error": "quota_exceeded" } | The workspace used its monthly allowance on the Free plan |
A double click is safe. If the same visitor sends identical answers twice within a minute, the second post gets the first submission's id back with "deduplicated": true and is not stored, emailed or counted again. Code that retries on its own can send a hidden _idempotency_key field instead, which holds for 24 hours.
Lock it to your domain
By default, any site can post to your endpoint. Once your form is live, add your origin, for example https://example.com, under Settings → Validation and abuse → Allowed origins. The match is exact, so add https://www.example.com too if you serve both.
The allowlist also controls _redirect. A hidden _redirect field can send each form to its own thank-you page, but SagePigeon only follows it when it points at an allowlisted origin. Otherwise it uses the form's own Redirect after submit, so nobody can turn your endpoint into an open redirect.
Prove it before you ship
On the Setup tab, press Send a test submission. It posts to the live endpoint the way your site would and then shows you the stages: stored, notification sent, waiting for a reply. If the test from the dashboard works and your site does not, the curl snippet on the same tab posts from outside the browser, which rules out an origin or script problem.
From here, the spam guide covers the honeypot, rate limits and captchas in more depth, the Slack walkthrough gets submissions into a channel, and the docs list every option.
Questions people ask
Can I send the form as FormData with fetch?
Send it as JSON or as URL-encoded form data instead. SagePigeon reads application/json and application/x-www-form-urlencoded bodies; a multipart FormData body is not read as fields.
What does my visitor see after submitting?
Your thank-you page, once you set it under Settings → Delivery → Redirect after submit. Until then, a plain SagePigeon page that tells them the message was sent and names your form. Load formsage.js to keep them on your own page instead.
Does it work without JavaScript?
Yes. A plain HTML form posts to the endpoint and the browser follows the redirect you set. formsage.js is optional and only adds in-page submission and failure reports.
How do I stop other sites posting to my form?
Add your site's origin, such as https://example.com, under Settings → Validation and abuse → Allowed origins. Browser posts from any other origin are refused with origin_not_allowed.