Forms

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.

Plain HTML
<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.

JSON from JavaScript
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. _gotcha is 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_confirmations on the create or update that would pass it, before anything is saved). The form's pendingEmails lists the addresses still waiting.
  • Spam trap. A submission with _gotcha filled 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 allowedOrigins set, a browser post from any other site is refused with 403 origin_not_allowed. This stops other websites using your form; it cannot stop a script, which can claim any origin.
The public key is not a secret
Anyone can read the 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.

form.submitted
{
  "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}: change name, isActive, notifyEmails (up to 10), allowedOrigins (up to 20, each like https://www.example.com) or redirectUrl.
  • GET /api/v1/forms/{id}/submissions: submissions, newest first. limit is 1 to 200 (default 50); page with cursor.
Create a form
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"
  }
}
Read submissions
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.