Site Forms
A site form is a form on your own website (a contact form, a lead form, a "get a quote" form) that posts straight to Throttle. Throttle keeps every submission and can email it to the addresses you set. Create forms in the dashboard under Forms, or with the API below.
Add a form to your site
Each form has a publicKey starting with frm_. Post your form to POST /api/v1/form-submissions/{publicKey}. No API
key is needed, and none should ever go in a web page.
<form action="https://api.usethrottle.dev/api/v1/form-submissions/frm_3f9c2a1b7d4e8f60a1b2c3d4" method="POST">
<label>Name <input name="name" required></label>
<label>Email <input name="email" type="email" required></label>
<label>Message <textarea name="message"></textarea></label>
<!-- Spam trap: keep it hidden and empty -->
<input name="_gotcha" style="display:none" tabindex="-1" autocomplete="off">
<button type="submit">Send</button>
</form>
A plain HTML post is answered with a 303 redirect to the
form's redirectUrl, or a simple thank-you page when none is
set. To submit from your own code, post JSON instead and you get JSON back.
const res = await fetch(
'https://api.usethrottle.dev/api/v1/form-submissions/frm_3f9c2a1b7d4e8f60a1b2c3d4',
{
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ name: 'Ada', email: '[email protected]', interests: ['pricing', 'demo'] }),
},
);
// 201 { "data": { "submitted": true } } What gets stored
- Any field names. You don't declare fields in advance; every field posted is saved as sent.
- Values may be text, numbers, true/false, or a list of those (up to 50 items). Nested objects are refused.
- Limits: at most 50 fields, field names up to 100 characters, values up to 10,000 characters, and a 64 KB body.
- Reserved names. Fields starting with
_are never stored._gotchais the spam trap. - Repeated names in a plain HTML post (for example a group of checkboxes sharing one name) keep only the last value. Give each checkbox its own name, or post JSON with a list.
Spam and abuse protection
- Emails go only to the form's own addresses. They are set on the form and can never come from a submission, so the endpoint cannot be used to send mail to anyone else.
- Addresses outside your team confirm first. Your workspace members' own addresses
are notified straight away. Any other address (a shared
sales@inbox, say) is sent a confirmation email and receives nothing until someone clicks Confirm on the page it links to. One confirmation covers every form in the workspace. Saving the form again re-sends an unconfirmed address its link, at most once a day and three times in all. A workspace can send at most 20 confirmation emails a day (429 too_many_confirmationson the create or update that would pass it, before anything is saved). The form'spendingEmailslists the addresses still waiting. - Spam trap. A submission with
_gotchafilled in gets the normal success answer, but nothing is stored or sent. - Rate limit: 10 submissions a minute from one IP address, answered with
429 rate_limit_exceeded. - Allowed sites (optional). With
allowedOriginsset, a browser post from any other site is refused with403 origin_not_allowed. This stops other websites using your form; it cannot stop a script, which can claim any origin.
publicKey in your page, and that is expected. Turn a form off (isActive: false) to stop
it accepting submissions.
Submission errors
404 form_not_found: unknown key, or the form is turned off.403 origin_not_allowed: the post came from a site not on the list.400 empty_submission: no fields were posted.400 invalid_submission: a value or the field count broke a limit above.429 rate_limit_exceeded: too many submissions from one address.
A plain HTML post gets these as a short page instead of JSON, with the same status code.
Get submissions by webhook
Subscribe a webhook endpoint to form.submitted (it needs forms:read) to receive every submission, alongside or instead of
email. It fires for each stored submission; spam-trap hits are not delivered. See webhooks for signing and retries.
{
"type": "form.submitted",
"data": {
"submission": {
"id": "c0ffee00-1111-2222-3333-444455556666",
"formId": "8b1d6f0e-2c3a-4e5b-9d7f-0a1b2c3d4e5f",
"formName": "Contact us",
"data": { "name": "Ada", "email": "[email protected]", "message": "Do you ship to Canada?" },
"origin": "https://www.example.com",
"createdAt": "2026-11-13T09:30:00.000Z"
}
}
}
The event log (GET /api/v1/events) records only the ids. Reading a
stored delivery back shows submission.data and origin only to a caller holding both forms:read and customer_pii:read.
Manage forms with the API
These routes take a secret key (sk_) and act in the key's
environment. They need forms:write to create or change a form and forms:read to read forms and submissions. Both are marked sensitive,
because submissions hold whatever visitors typed. See scopes.
POST /api/v1/forms: create a form.GET /api/v1/forms: list the environment's forms.GET /api/v1/forms/{id}: read one form.-
PATCH /api/v1/forms/{id}: changename,isActive,notifyEmails(up to 10),allowedOrigins(up to 20, each likehttps://www.example.com) orredirectUrl. -
GET /api/v1/forms/{id}/submissions: submissions, newest first.limitis 1 to 200 (default 50); page withcursor.
curl -X POST https://api.usethrottle.dev/api/v1/forms \
-H "x-api-key: $THROTTLE_SECRET_KEY" \
-H "content-type: application/json" \
-d '{
"name": "Contact us",
"notifyEmails": ["[email protected]"],
"allowedOrigins": ["https://www.example.com"],
"redirectUrl": "https://www.example.com/thanks"
}'
# 201
{
"data": {
"id": "8b1d6f0e-2c3a-4e5b-9d7f-0a1b2c3d4e5f",
"name": "Contact us",
"publicKey": "frm_3f9c2a1b7d4e8f60a1b2c3d4",
"isActive": true,
"notifyEmails": ["[email protected]"],
"pendingEmails": ["[email protected]"],
"allowedOrigins": ["https://www.example.com"],
"redirectUrl": "https://www.example.com/thanks",
"createdAt": "2026-11-13T09:00:00.000Z",
"updatedAt": "2026-11-13T09:00:00.000Z"
}
} curl "https://api.usethrottle.dev/api/v1/forms/$FORM_ID/submissions?limit=50" \
-H "x-api-key: $THROTTLE_SECRET_KEY"
# 200, newest first
{
"data": [
{
"id": "c0ffee00-1111-2222-3333-444455556666",
"formId": "8b1d6f0e-2c3a-4e5b-9d7f-0a1b2c3d4e5f",
"data": { "name": "Ada", "email": "[email protected]", "message": "Do you ship to Canada?" },
"origin": "https://www.example.com",
"emailStatus": "delivered",
"emails": [{ "email": "[email protected]", "status": "delivered" }],
"createdAt": "2026-11-13T09:30:00.000Z"
}
],
"meta": { "requestId": "req_...", "pagination": { "hasMore": false, "cursor": null } }
}
# Next page: pass meta.pagination.cursor back as ?cursor= emails lists each notification email with its recipient and status, and emailStatus sums them up. A status is one of:
queued: waiting to go out.sent: handed to the mail provider, not yet accepted by the recipient's mail server.-
delivered: accepted by the recipient's mail server. If it isn't in the inbox after that, look in spam, other tabs and any mail filters. bounced: the recipient's mail server refused it.failed: it could not be sent.-
skipped: nothing was sent (no address on the form is confirmed yet, or notification emails are turned off).
emailStatus reports a failure or bounce first; otherwise it shows the recipient
that is furthest behind, so one stuck email is not hidden behind delivered ones. A failed email never loses
the submission. Forms in a non-production environment send their email with a [TEST] banner on the subject.