Astro contact form that sends email
Formgong team ·
An Astro contact form is a plain form in an .astro file that posts to Formgong. It works with output set to static, so you do not add an adapter, an Astro Action, or a Resend key. Telegram is instant. Email arrives for each submission, on the free plan too.
Static Astro contact form
Save this as src/components/ContactForm.astro and render it on the contact page.
The form is HTML. It works with JavaScript off. Astro does not add an island unless you ask for one.
Set the action to the Formgong submit URL. A static page has nothing listening for its own POST.
The access key is public. It can submit this form. It cannot read the inbox.
Free stores 250 submissions a month and emails each one right away to up to 3 verified addresses.
Telegram is instant on every plan, including Free. There is no auto-reply on Free.
Pro allows 5 email recipients.
---
// src/components/ContactForm.astro
// A static build. output: "static" is the default. No adapter.
const endpoint = "https://formgong.com/submit";
---
<form action={endpoint} method="POST">
<input type="hidden" name="access_key" value="YOUR_ACCESS_KEY" />
<input type="hidden" name="_lang" value="en" />
<label for="name">Name
<input id="name" type="text" name="name" autocomplete="name" required />
</label>
<label for="email">Email
<input id="email" type="email" name="email" autocomplete="email" required />
</label>
<label for="message">Message
<textarea id="message" name="message" required></textarea>
</label>
<div aria-hidden="true" style="position:absolute;inset-inline-start:0;top:0;width:1px;height:1px;overflow:hidden;clip-path:inset(50%)">
<label>Leave this empty
<input type="text" name="botcheck" tabindex="-1" autocomplete="off">
</label>
</div>
<button type="submit">Send</button>
</form>Stay on the page with a script. No framework island.
<!-- Add id="astro-contact" and <p role="status"></p> to the form above. -->
<script>
const form = document.querySelector("#astro-contact");
const status = form.querySelector("[role=status]");
form.addEventListener("submit", async (event) => {
event.preventDefault();
if (!form.reportValidity()) return;
const button = form.querySelector("button");
button.disabled = true;
status.textContent = "";
try {
const response = await fetch(form.action, {
method: "POST",
headers: { Accept: "application/json" },
body: new FormData(form),
});
const result = await response.json();
const ok = response.ok && result.success;
status.textContent = result.message || (ok ? "Thanks. We have your message." : "Could not send. Try again.");
status.setAttribute("role", ok ? "status" : "alert");
if (ok) form.reset();
} catch {
status.textContent = "Could not send. Check your connection and try again.";
status.setAttribute("role", "alert");
} finally {
button.disabled = false;
}
});
</script>Astro Actions and on-demand rendering
Use an Action or an endpoint when the submit must reach your own database or a private API.
Both need an adapter. A page sets prerender to false. output server makes that the default.
Do not add an adapter only for this contact form. The static form above already delivers the lead.
A server forward sends every lead from your server IP. That weakens rate limits and spam signals.
@formgong/astro exports forwardToFormgong for an Action. The sample uses fetch so every field is visible.
Server Action that forwards the fields
// src/actions/index.ts
// Needs an adapter and on-demand rendering. A static build cannot run this.
// Docs: defineAction, accept: "form", and z from astro/zod.
import { defineAction } from "astro:actions";
import { z } from "astro/zod";
export const server = {
contact: defineAction({
accept: "form",
input: z.object({
name: z.string().min(1),
email: z.string().email(),
message: z.string().min(1),
}),
handler: async (input) => {
const response = await fetch("https://formgong.com/submit", {
method: "POST",
headers: { "Content-Type": "application/json", Accept: "application/json" },
body: JSON.stringify({
access_key: import.meta.env.FORMGONG_ACCESS_KEY,
_lang: "en",
name: input.name,
email: input.email,
message: input.message,
}),
});
const result = await response.json();
if (!response.ok || !result.success) {
throw new Error(result.message || "Could not send.");
}
return { message: result.message || "Thanks. We have your message." };
},
}),
};Endpoint that reads request.formData()
// src/pages/api/contact.ts
// Also needs prerender = false and an adapter. Static builds skip this file.
import type { APIRoute } from "astro";
export const prerender = false;
export const POST: APIRoute = async ({ request }) => {
const data = await request.formData();
const response = await fetch("https://formgong.com/submit", {
method: "POST",
headers: { Accept: "application/json" },
body: data,
});
const result = await response.json();
return new Response(JSON.stringify(result), {
status: response.ok && result.success ? 200 : response.status,
headers: { "content-type": "application/json" },
});
};astro.config.mjs for a static site
// astro.config.mjs
import { defineConfig } from "astro/config";
export default defineConfig({
output: "static",
});| Static form | Action or endpoint | Email API such as Resend | |
|---|---|---|---|
| Where it runs | In the browser. The host only serves files. | On your server, after you add an adapter. | On a server you run, with an API key. |
| Static build | Works. output static is enough. | Does not run. Actions need on-demand rendering. | Does not run. You need a server. |
| Secrets | The access key is public. It cannot read the inbox. | The key can stay in an env var. It is still a public key. | The API key must stay on the server. |
| Right away for each lead, on every plan. | Same Formgong rules. The POST comes from your server IP. | Mail leaves when their API accepts it, from a domain you verify. | |
| Telegram | Instant on every plan, including Free. | Same, if you forward the fields. | Not included. |
These calls follow the Astro Actions guide and the forms recipe, checked on 6 October 2026.
What Astro.request.formData() returns
Astro.request is the request for the page. formData() reads a POST body as FormData.
Check the method, then call formData() inside try and catch. A body that is not a form throws.
data.get returns a string or a File. Check the type before you use it.
On a static build this code never runs. The HTML is already written.
Read a POST inside a page
---
// src/pages/contact.astro
// This runs only when the page is rendered on demand.
export const prerender = false;
let notice = "";
if (Astro.request.method === "POST") {
try {
const data = await Astro.request.formData();
const email = data.get("email");
notice = typeof email === "string" ? "Got " + email : "Missing email";
} catch (error) {
notice = error instanceof Error ? error.message : "Could not read the form";
}
}
---
<p>{notice}</p>Deploy on Cloudflare Pages or Netlify
A static Astro build writes the dist folder. Point the host at dist.
Cloudflare Pages does not need a Pages Function for this form. Netlify does not need a Function either.
Skip data-netlify. That attribute feeds Netlify's own inbox, and this form does not use it.
A hidden _redirect must stay on the same site. An off-site URL is dropped.
Host notes are on the Cloudflare Pages contact form and the Netlify contact form. The same HTML job on any static host is a static website contact form.
Error states
Treat the send as a success only when the HTTP status is OK and success is true.
Read code and message from the JSON. The message is already translated for _lang.
Leave botcheck empty. The same trap also answers to _gotcha, _honey and _honeypot.
A filled honeypot is stored as spam. It is not emailed, it is not sent to Telegram, and it does not use the monthly quota.
If the page sends _ts and the form arrives in under 1.5 seconds, that lead is scored as spam too.
Turnstile is optional on every plan. It is required when a file is attached. The secret stays in Formgong.
| Code | What it means | What to do |
|---|---|---|
| rate_limited | 429. More than 30 posts a minute for this form, or 20 from one IP. | Wait a minute. Show the message and leave the fields filled. |
| limit_exceeded | The account used its monthly submissions. Free is 250. | The lead is not stored or delivered: the account is over its limit and its held submissions are full. The owner upgrades the plan or buys a pack. |
| unknown_access_key | 404. That access key does not match a form. | Copy the key again from Formgong. A placeholder key always fails. |
| turnstile_missing | Turnstile is on, or a file is attached, and the token was not posted. | Add the widget only after you turn protection on. The field name is cf-turnstile-response. |
| turnstile_failed | Cloudflare rejected the token. | Load the widget again and submit once. Check the site key. |
| too_large | 413. The text body is over 64 KB, or a file is over the upload cap. | Shorten the message, or send fewer files. The cap is 3 files, 5 MiB each, 10 MiB total. |
| origin_not_allowed | A domain list is on, and this host is not in it. | Add the live host. Every plan, Free included, has the domain list. |
Starter and the npm package
@formgong/astro is 0.1.0, published on 3 October 2026. The README shows ContactForm and FormgongForm.
The package does not change the plan or its limits.
The Astro starter on GitHub is a working site under the MIT license.
ContactForm from the package
--- import ContactForm from "@formgong/astro/ContactForm.astro"; --- <ContactForm accessKey="YOUR_ACCESS_KEY" lang="en" />
Collecting a lead without a backend is on the blog. After a plain POST, use a thank-you page. Quotas are on the pricing page.
How forms work in Astro
Astro builds static pages by default and ships no JavaScript unless you add an island. Astro Actions and API endpoints run on a server, so they need an adapter and on-demand rendering. For a contact form on a static site that is a lot of setup.
A plain HTML form in an .astro component posts to https://formgong.com/submit and needs neither. The page stays static, the form works without JavaScript, and the visitor lands on a thank-you page in their language or on your own _redirect page.
Set it up in Astro
- Create a form in Formgong and copy the access key.
- Paste the snippet below into an
.astrocomponent, replace the key and set_langfrom the page language. - Add a hidden
_redirectfield pointing to a thank-you page in your site, if you have one. - Build as usual;
output: 'static'is fine. Deploy and send a test. The lead is in the inbox. Telegram and email arrive right away. - Optional: wrap the form in an island with a framework component if you want the answer to appear without leaving the page.
Ready starter on GitHub: github.com/formgong/astro-starter. MIT license: click “Use this template” or copy the files.
New project in one command: npm create formgong@latest -- --template astro (npm: create-formgong)
Component package: npm install @formgong/astro (npm: @formgong/astro)
Add to an existing project: npx formgong init (npm: formgong)
Formgong or Astro Actions?
Astro Actions fit when the site already runs on a server adapter and the submission must reach your own code.
For static sites and simple contact or lead forms, posting to Formgong keeps the build static and removes server code.
Questions and answers
Do I need an adapter?
No. The form posts to Formgong, so a static build is enough.
Can I show the result without leaving the page?
Yes. Use a small island with fetch, or Formgong's optional fg.js script.
Is there a ready project?
Yes. The Astro starter on GitHub is a working site with this form, under the MIT license.
Articles on this topic
Related pages
Guides
- Formgong for agencies
- Static website contact form
- Netlify Forms alternative
- GDPR-compliant contact form
- Formspree alternatives
- Formcarry alternatives
- Formspark alternatives
- Splitforms alternatives
- Formgrid alternatives
- FormBackend alternatives
- Formbold alternatives
- Formester alternatives
- HeroTofu alternatives
- KwesForms alternatives
- Sheet Monkey alternatives
- Slapform alternatives
- Static Forms alternatives
- ShipMyForm alternatives
- Contact Form 7 alternatives
- WPForms alternatives
- Zapier Forms alternatives
- Forminit alternatives
- Fillout alternatives
- Formstack alternatives
- Microsoft Forms alternatives
- Paperform alternatives
- Freedback alternatives
- Pageclip alternatives
- EmbedSocial alternative
- Trustindex alternative
- Senja alternative
- Shapo alternative
- Junip alternative
- Famewall alternative
- FormKeep alternatives
- Jotform alternatives
- Basin alternatives
- Getform alternatives
- FormSubmit alternatives
- Typeform alternatives
- Tally alternatives
- Wufoo alternatives
- Google Forms alternatives
- Formgong alternatives
- Formsite alternatives
- Form for photographers
- Form for restaurants
- Form for clinics
- Form for real estate
- Form for lawyers
- Best form backend services
- Form endpoint services tested
- Contact form APIs tested
- Web3Forms alternatives
- EmailJS alternatives
- Formspree vs Web3Forms
- Formspree vs EmailJS
- Formspree vs Getform (Forminit)
- Formspree vs Basin
- Formspree vs FormSubmit
- Web3Forms vs Netlify Forms
- Netlify Forms vs Formspree
- Jotform vs Typeform
- Judge.me vs Yotpo
- Judge.me vs CusRev: the WooCommerce question
- Best free form backends
- Free website templates
- Testimonial and rating widget
- Judge.me alternative
- Yotpo alternative
- Loox alternative
- Stamped alternative
- Okendo alternative
- Fera alternative
- CusRev alternative
- Trustpilot alternative
- Testimonial.to alternative
- Elfsight alternative
- Trustmary alternative
- Boast alternative
- REVIEWS.io alternative
- Endorsal alternative
- AI builder prompts
- Form checker
- AI form generator
- Form builder
- Tailwind form generator
- Bootstrap form generator
- Booking form generator
- Order form generator
- Registration form generator
- Contact form generator
- HTML form generator
- HTML form builder
- Survey form generator
- Feedback form generator
- Newsletter signup form generator
- RSVP form generator
- Job application form generator
- Review schema generator
- Google review link generator
- Contact form examples
- HTML contact form code
- React contact form component
- Next.js contact form template
- Tailwind contact form template
- Shopify contact form Liquid
- Webflow contact form code
- Framer contact form component
- Astro contact form component
- Vue contact form component
- Ghost contact form
- WordPress contact page template
- Agent rules files
- Tools