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.

ContactForm.astro
---
// 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.
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
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()
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 for a static site
// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  output: "static",
});
Static form, Astro Action, and an email API
Static formAction or endpointEmail API such as Resend
Where it runsIn 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 buildWorks. output static is enough.Does not run. Actions need on-demand rendering.Does not run. You need a server.
SecretsThe 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.
EmailRight 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.
TelegramInstant 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
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.

Formgong error codes for a contact form
CodeWhat it meansWhat to do
rate_limited429. 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_exceededThe 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_key404. That access key does not match a form.Copy the key again from Formgong. A placeholder key always fails.
turnstile_missingTurnstile 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_failedCloudflare rejected the token.Load the widget again and submit once. Check the site key.
too_large413. 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_allowedA 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
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

  1. Create a form in Formgong and copy the access key.
  2. Paste the snippet below into an .astro component, replace the key and set _lang from the page language.
  3. Add a hidden _redirect field pointing to a thank-you page in your site, if you have one.
  4. Build as usual; output: 'static' is fine. Deploy and send a test. The lead is in the inbox. Telegram and email arrive right away.
  5. 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.

Start free