Documentation
MailForm gives every form one endpoint: POST /api/v1/submit. Send it your API key plus any fields you want, and it emails the submission to the recipients configured for that form.
1. Create a form
Sign in to the control panel, click New form, and give it a name. You'll get an API key immediately — configure recipients, reply-to, and the daily limit whenever you like.
2. Add it to your app
Pick your stack below for a ready-made snippet, or paste the universal prompt into your AI coding assistant and let it wire everything up for you.
Fastest way to set this up
Paste this into your AI coding assistant
Works in Claude Code, Cursor, Copilot Chat, or any AI coding tool with access to your codebase. It figures out your framework, asks for your API key, and wires everything up.
Set up a MailForm submission form in this project.
Before writing any code, ask me:
1. Which page/component the form should live on, and what fields it should collect.
2. My MailForm API key for this form (looks like "mf_live_xxxxxxxx").
Once I answer:
1. Detect this project's framework/stack (React, Next.js, Vue, Svelte, plain HTML, Expo, or anything else) by inspecting package.json and existing files — don't ask me what stack this is.
2. Add a form with the fields I specified to the page/component I named, matching the existing code style and UI.
3. On submit, send a POST request to https://mailform.retaillian.com/api/v1/submit with header "X-API-Key: <the key I gave you>" and a JSON body of the field values (for a plain static HTML site with no JavaScript, use <form action="https://mailform.retaillian.com/api/v1/submit" method="POST"> with a hidden "apikey" input instead).
4. Redirect behavior — controlled by an optional "_redirect" field/param, same on GET and POST:
- GET requests redirect to MailForm's built-in thank-you page by default. Pass _redirect=false to get JSON instead.
- POST requests return JSON by default (what a JS-driven form needs to show inline success/error state) — they do NOT redirect unless you set _redirect=true (built-in page) or _redirect=<url> (your own page). If you're building a plain, JavaScript-free HTML form (method="POST"), add a hidden field "_redirect" set to "true" so the visitor lands somewhere after submitting.
5. Handle the response for JS-driven forms: show a success message on { "success": true }, and show the "error" message on failure, with a friendly note for HTTP 429 (daily limit reached).
6. Don't hardcode personal data — use the values from the form inputs.
Confirm both answers with me before writing any code.Or set it up yourself, framework by framework:
<!-- GET links/forms redirect to MailForm's thank-you page automatically. -->
<!-- POST forms don't redirect by default — add _redirect to opt in. -->
<form action="https://mailform.retaillian.com/api/v1/submit" method="POST">
<input type="hidden" name="apikey" value="mf_live_xxxxxxxx" />
<input type="hidden" name="_redirect" value="true" />
<!-- or: value="https://yoursite.com/thanks" to use your own page -->
<input type="text" name="name" placeholder="Your name" required />
<input type="email" name="email" placeholder="Your email" required />
<textarea name="message" placeholder="Message" required></textarea>
<button type="submit">Send</button>
</form>Set up a MailForm submission form in this plain HTML/JS project.
Before writing any code, ask me two things (skip whichever I've already told you):
1. Which page or component the form should be added to, and which fields it should collect.
2. My MailForm API key for this form (looks like "mf_live_xxxxxxxx").
Once I answer, implement it:
- Add a form with the fields I listed, styled to match this project's existing UI.
- On submit, send a POST request to https://mailform.retaillian.com/api/v1/submit with header "X-API-Key: <the key I gave you>" and a JSON body containing the field values.
- Show a success message when the response is { "success": true }, and show the "error" message from the response on failure — including a friendly note if the status is 429 (daily submission limit reached).
- This is a plain, JavaScript-free HTML form, so use method="POST" with a hidden field named "apikey" instead of a header. POST does not redirect by default — add a hidden field "_redirect" set to "true" (redirects to MailForm's built-in thank-you page) or to your own URL, so the visitor lands somewhere after submitting.
- Don't hardcode any personal data; use the values typed into the form.
Confirm you have both answers before writing code.3. Authenticate
Pass your API key one of three ways:
X-API-Keyrequest header (recommended for fetch/JS)apikeyquery parameter (works for GET links and simple forms)apikeyfield in a JSON or form-encoded body
4. Send a submission
Any other field you send becomes a row in the email. A few field names are reserved:
emailorreply_to— used as the email's Reply-To address if the form doesn't have one configured_redirect— controls what happens after a successful submission. See Redirects after submit below.
5. Redirects after submit
MailForm hosts a generic, friendly “thanks” page so plain HTML forms have somewhere to land without you building one. The default behavior differs by method, and both are controlled by the same optional _redirect field:
- GET requests redirect by default. A plain link or a
method="GET"form sends the visitor to MailForm's built-in success page automatically. Pass_redirect=falseto disable this and get a JSON response instead (what you want for fetch/AJAX calls made via GET). - POST requests don't redirect by default — they return JSON, which is what fetch/AJAX-based forms (React, Vue, Svelte, etc.) expect. If you're submitting a plain, JavaScript-free
<form method="POST">, add a hidden field_redirect=trueto send the visitor to the built-in success page too. - Any request, any method: set
_redirectto your own URL (e.g.https://yoursite.com/thanksor a relative path like/thanks) to redirect there instead of the generic page.
_redirect=false Force JSON, no redirect (overrides the GET default)
_redirect=true Redirect to MailForm's generic success page (opt in on POST)
_redirect=<url> Redirect to your own URL, on either GET or POST
(not set) GET → redirects to the generic page · POST → returns JSONExamples
cURL
curl -X POST https://mailform.retaillian.com/api/v1/submit \
-H "X-API-Key: mf_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"name": "Jane Doe", "email": "jane@example.com", "message": "Hi there!"}'GET request (query string)
https://mailform.retaillian.com/api/v1/submit?apikey=mf_live_xxxxxxxx&name=Jane&email=jane@example.com&message=HiResponse format
On success:
{ "success": true, "id": "clx1a2b3c4d5" }On failure (invalid key, missing recipients, or daily limit reached):
{ "success": false, "error": "Daily limit of 20 submissions reached for this form." }Rate limits
Every form has a daily email limit — 20 by default. Once the limit is hit for the day, the endpoint responds with HTTP 429 until midnight. You can raise, lower, or remove the limit per form in the control panel.
Playground
Want to try a request without leaving your browser? Use the playground in the control panel — pick a form, add fields, and send a real test submission.