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.

Universal setup prompt

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, you may instead use <form action="https://mailform.retaillian.com/api/v1/submit" method="POST"> with a hidden "apikey" input).
4. Handle the response: show a success message on { "success": true }, and show the "error" message on failure, with a friendly note for HTTP 429 (daily limit reached).
5. 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:

index.html

<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="https://yoursite.com/thanks" />
  <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>

AI prompt — HTML

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).
- 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-Key request header (recommended for fetch/JS)
apikey query parameter (works for GET links and simple forms)
apikey field 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:

email or reply_to — used as the email's Reply-To address if the form doesn't have one configured
_redirect — if present, the API redirects the browser here after a successful plain HTML form submission

Examples

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=Hi

Response 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.