You pushed your portfolio to GitHub Pages, added a contact form, and clicked Send. Nothing arrived, and the visitor saw an error page or a dead refresh. Every message you miss this way is a lead or a job offer that never reached you. A contact form for GitHub Pages only works if the form posts to something that can actually accept it, and the site itself cannot.
SimpleForm is a hosted form backend for static sites: you point an HTML form at a SimpleForm endpoint, and it stores the submission, filters spam, and emails you. This guide shows the full setup, the two ways to handle the response, and the errors you are most likely to hit.
Why can't GitHub Pages handle a contact form on its own?
GitHub Pages can't process a form because it only serves files and never runs code on a request. When a browser sends a POST to a page on a static host, the host has no program to hand that request to, so it replies with an error or ignores the body.
That is a property of static hosting in general, not a GitHub quirk. The action attribute of a form tells the browser where to send the data, as described in the MDN reference for the form element. If the action is empty or points at your own static page, the data goes nowhere useful.
You therefore have three options: write and host your own endpoint, use a serverless function, or send the form to a hosted form backend. The first two mean running something you then have to maintain. This post sticks to the hosted route.
How do you add a contact form to GitHub Pages?
You add a contact form to GitHub Pages in five steps: create an endpoint, paste its URL into your form's action, name your fields, set a thank-you page, and test from the live URL. None of it needs a build step, so it works the same in plain HTML, Jekyll, or any static generator that outputs HTML.
- Create a free SimpleForm account and add a form in the dashboard. You get an endpoint of the form
https://simpleform.dev/f/TOKEN. - Set the form's
actionto that URL and itsmethodtoPOST. - Give every input a
nameattribute. Fields without a name are not sent by the browser. - Set a Redirect URL in the form settings to a thank-you page in your repository, for example
/thanks.html. - Commit, wait for the Pages deployment, and submit the form from the live URL, not from a local file.
Here is the minimal markup. It has no JavaScript at all:
<form action="https://simpleform.dev/f/TOKEN" method="POST">
<label for="name">Name</label>
<input id="name" name="name" type="text" required>
<label for="email">Email</label>
<input id="email" name="email" type="email" required>
<label for="message">Message</label>
<textarea id="message" name="message" required></textarea>
<button type="submit">Send</button>
</form>Replace TOKEN with the token from your dashboard. A standard POST like this is accepted, stored, and then redirected to your thank-you page.
Should you use a redirect or a JSON response?
Use a redirect when you want the least code, and a JSON response when you want to keep the visitor on the page. The choice is made by the request, not by a setting: a plain form post gets a redirect, and a request that sends the header Accept: application/json gets a JSON body back.
| Approach | What you write | What the visitor sees | Best for |
|---|---|---|---|
| Plain HTML post with Redirect URL | Form markup only | Full page load to your thank-you page | Portfolios, simple landing pages |
| Fetch with Accept: application/json | Form markup plus a short script | Inline success or error message, no navigation | Single-page layouts, forms with custom feedback |
My view: start with the redirect. It is the version with the fewest ways to break, and a thank-you page is also a clean place to measure conversions later. Move to JSON only when a full page load genuinely hurts the design.
If you do go the JSON route, this is the whole script:
const form = document.querySelector('form');
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();
if (data.success) form.reset();
});The e.preventDefault() call matters, and forgetting it is the most common reason a page reloads anyway.
At this point the manual route gets tedious: you would be writing the receiving endpoint, the spam filter, the email delivery, and the storage yourself. SimpleForm does those four jobs for the endpoint, and the SimpleForm documentation lists the request formats and response codes it accepts.
What breaks on a GitHub Pages form, and how do you fix it?
Most failures show up as a specific HTTP status, and each status points at one cause. The SimpleForm docs list the response codes below, so you can read the status in your browser's network tab and skip the guesswork.
| Status | Likely cause on GitHub Pages | Fix |
|---|---|---|
| 400 | Fields have no name attribute, or the body is empty | Add a name to every input |
| 402 | Monthly submission limit reached | Wait for the reset on the first of the month, or upgrade |
| 403 | Request came from a domain you did not allow | Add your github.io or custom domain to the allowed list |
| 404 | Token is wrong or the endpoint is inactive | Copy the token again from the dashboard |
| 429 | Too many submissions from one IP | Wait, then retest more slowly |
The 429 deserves a note because you will trigger it yourself while testing. SimpleForm limits submissions to 10 per IP address per endpoint per hour, so ten rapid test posts will lock you out of your own form for a while. Test with a few real entries rather than a loop.
A separate failure that has nothing to do with the status code: a submission that returns success but never reaches your inbox. That is usually a mail filtering problem, so check your spam folder before you change any markup.
Can you lock the endpoint to your GitHub Pages domain?
Yes, on the Pro plan, which includes domain restriction. Once set, requests from any origin other than the ones you list return 403, which stops someone copying your endpoint token from the page source and posting from their own site.
Your token is visible in your HTML, because it has to be. That is not a leak, since the token only allows submitting, not reading. But without restriction, anyone can send junk to it and use up your monthly allowance.
For a GitHub Pages site, you have two origins to think about: the default username.github.io address and any custom domain you attach. List whichever visitors actually use.
Will the Free plan be enough for a GitHub Pages site?
For a portfolio or a small project site, usually yes. The Free plan includes 100 submissions per month, 3 forms, 7-day submission storage, honeypot spam protection, one email recipient, and a custom redirect URL, with no credit card required.
The honest objection is that you could write a serverless function instead and pay nothing. You could, and if you already run a cloud account and want full control over the payload, that is a fair choice. What you take on is the spam filtering, the email deliverability, the storage, and the on-call duty when it stops working. A hosted endpoint trades a small plan limit for not owning those parts.
The limits to watch are the 7-day storage window and the single recipient. If you need a team inbox or a longer archive, the pricing page lists what the paid plans add, and Pro is $9 per month or $90 per year.
Next step: send your first test submission
Create a free SimpleForm account, add one form, and paste its endpoint into your GitHub Pages form. Submit it once from your live site, and the entry should appear in your dashboard and your inbox within moments, which confirms the whole path works before a real visitor tries it.
Frequently asked questions
Yes. GitHub Pages hosts the page for free, and SimpleForm's Free plan covers the form backend with 100 submissions per month, 3 forms, and 7-day submission storage. No credit card is required. You only pay if you need more volume, longer storage, or features such as domain restriction.
The form is posting to your own static page, which cannot accept a POST. Check that the action attribute points at your form backend's endpoint URL, not at a relative path or an empty value. If the endpoint itself returns 404, the token is wrong or the form is inactive.
No. A standard HTML form with an action URL and the POST method works with no scripting. Add JavaScript only if you want an inline success message instead of a redirect, in which case you send the request with an Accept: application/json header and read the JSON response.
Yes, because the token only allows submitting data, not reading it. It is visible in your page source regardless. To stop others from posting to it from their own sites, restrict the endpoint to your allowed domains, which returns a 403 for any other origin.
Submissions over your monthly limit return a 402 response and are not stored. Usage resets on the first of each month. SimpleForm does not silently overcharge you, so you can either wait for the reset or move to a higher plan from the billing dashboard.