Submissions

A submission is a single data entry received at a form’s endpoint. Every POST to your endpoint creates one submission.

Lifecycle

When data hits your endpoint:

1. Validated - Data is checked against the form schema (required fields, types, constraints)
2. Accepted - The endpoint responds 201 Created immediately
3. Processed - Spam detection, translation, and smart replies run asynchronously
4. Notified - Webhooks, Discord/Slack connectors, and email notifications fire after processing

If spam is caught, the pipeline stops. Translation and smart replies are skipped for spam.

Sending a submission

POST JSON data to your endpoint:

curl -X POST https://usepostbox.com/api/.../f/{slug} \
  -H "Content-Type: application/json" \
  -d '{"name": "Grace Hopper", "email": "grace@example.com", "message": "Hello!"}'

Submissions accept Content-Type: application/json only. JSON payloads give you structured validation errors with per-field details.

CORS is handled automatically - submit from any origin.

Response

A successful submission returns 201 Created:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "message": "Hello!"
  },
  "created_at": "2026-03-09T10:10:20Z"
}

Processing status

Each submission tracks its progress through the async pipeline:

Status	Meaning
pending	Received, processing not yet started
processing	Currently being processed
completed	All pipeline steps finished (including when spam is detected)
skipped	AI processing skipped (free-tier user with no remaining credits)
failed	Processing encountered an error

The processing_reason field provides context when processing does not complete normally (e.g., "ai_credits_exhausted" when skipped).

Submission fields

When you retrieve a submission via the API, it includes processing metadata:

Field	Description
spam_flag	true if flagged as spam, false otherwise
spam_confidence	AI confidence score (0.0 to 1.0), or null
spam_reason	Human-readable explanation of spam classification
original_language	Detected language code, or null
translated_data	Translated fields (if translation is enabled)
processing_status	Pipeline status (see above)
processing_reason	Explanation when processing is skipped or fails
reply_status	"pending", "completed", "sent", or "failed"
reply_content	Generated reply text, or null

Reading submissions

Use the management API to list and read submissions:

# List submissions for a form
curl https://usepostbox.com/api/forms/{form_id}/submissions \
  -H "Authorization: Bearer {api_key}"

# Get a single submission
curl https://usepostbox.com/api/forms/{form_id}/submissions/{id} \
  -H "Authorization: Bearer {api_key}"

Submissions are returned newest-first with pagination. You can filter by "inbox" (default, non-spam), "spam", or "all".

Spam handling

Submissions flagged as spam are still stored - they’re just marked. The submitter always receives a 201 response regardless of spam classification. You can review spam submissions in the dashboard or via the API.