How It Works
Understanding the form submission flow from user input to email delivery
Static Forms acts as a form backend service that processes form submissions and sends email notifications. This page explains the complete flow of how a form submission is handled from start to finish.
The Form Submission Flow
User Submits Form
When a user fills out and submits your HTML form, the browser sends a POST request to the Static Forms API endpoint:
API Receives Request
The Static Forms API receives the form data along with your API key. The API key is used to:
- Identify your account
- Verify authentication
- Apply your account settings (spam protection, auto-responders, etc.)
- Check usage limits
Validation & Processing
The API performs several validation and processing steps:
- API Key Validation: Verifies the API key is valid and active
- Spam Protection: Checks honeypot fields, reCAPTCHA tokens, or ALTCHA challenges if enabled
- Rate Limiting: Verifies you haven't exceeded monthly email limits
- File Validation: If files are uploaded, validates size and type (Pro tier)
- Data Sanitization: Cleans and prepares form data for email
Email Notification
If validation passes, Static Forms sends an email notification to the address associated with your account. The email includes:
- All form field names and values
- Submission timestamp
- File attachments (if any, Pro tier)
- Reply-to address (if configured)
Additional Actions
Depending on your account settings, additional actions may be triggered:
- Auto-Responder: Sends confirmation email to the submitter (Pro tier)
- Webhook: Sends POST request to your webhook URL (Pro tier)
- Submission Storage: Stores submission in dashboard (if enabled, Pro tier)
Response to User
The API responds to the browser with either:
- Success: Redirects to your
redirectToURL or returns JSON success response - Error: Returns error message with details about what went wrong
API Key Authentication
Your API key is the primary method of authentication. It's a unique identifier that:
- Links form submissions to your account
- Applies your account settings and preferences
- Enforces usage limits based on your plan tier
- Enables or disables features based on your subscription
API Key Security
API keys are safe to use in client-side code (HTML forms, JavaScript). They don't grant access to sensitive account operations. However, you should still keep them private and not commit them to public repositories.
Email Delivery Pipeline
Once a form submission is validated, the email delivery process works as follows:
1. Email Composition
Static Forms formats the email with all form field data. The email includes:
- Field names as labels
- Field values as content
- File attachments (if any)
- Submission metadata (timestamp, IP address if enabled)
2. Email Sending
Emails are sent via AWS SES (Simple Email Service) for reliable delivery. The email is sent from noreply@staticforms.dev to the email address associated with your account.
3. Delivery Status
Most emails are delivered within seconds. If delivery fails (bounce, spam filter, etc.), you may receive a notification depending on your email provider's settings.
Error Handling
If any step in the process fails, the API returns an appropriate error response:
| Error Type | HTTP Status | Description |
|---|---|---|
| Invalid API Key | 401 | API key is missing or incorrect |
| Rate Limit Exceeded | 429 | Monthly email limit reached |
| Spam Detected | 400 | Honeypot field filled or CAPTCHA failed |
| File Too Large | 400 | Uploaded file exceeds 5MB limit |
Pro Tip
For detailed information about error codes and responses, see the API Reference documentation.
What Happens to Form Data?
By default, Static Forms does not store form submissions. The data is:
- Processed in real-time
- Sent to your email address
- Discarded after email delivery
Pro Feature: Submission Storage
Pro tier users can optionally enable submission storage to view, export, and manage submissions in the dashboard. This feature must be explicitly enabled in your account settings.