API: Submissions

Submit data (public endpoint)

No authentication required for public forms. POST JSON data to a form’s endpoint:

POST https://usepostbox.com/api/.../f/{slug}

The full endpoint URL is in the endpoint field from form creation/retrieval. Don’t construct it manually.

Request

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

Accepts Content-Type: application/json only.

For private forms, include the submission token: -H "Authorization: Bearer {submission_token}"

Response (201 Created)

{
  "id": "eb72b858-4011-40dc-b707-8a3e67e13906",
  "data": {
    "name": "Alan Turing",
    "email": "alan@example.com",
    "message": "Hello"
  },
  "created_at": "2026-03-09T10:58:47Z"
}

Validation errors (400)

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "email": ["is required"],
      "age": ["invalid number"]
    }
  }
}

Unauthorized (401) - private form

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized (missing or invalid API key)"
  }
}

Plan limit reached (429) - free plan

{
  "error": {
    "code": "plan_limit_exhausted",
    "message": "Submission limit reached.",
    "upgrade_url": "https://usepostbox.com/settings/billing"
  }
}

Discover form schema

GET https://usepostbox.com/api/.../f/{slug}

Returns the form’s field schema so agents and scripts can discover what to submit:

{
  "name": "Contact",
  "slug": "contact",
  "fields": [
    { "name": "name", "type": "string", "required": true },
    { "name": "email", "type": "email", "required": true },
    { "name": "message", "type": "string", "required": false }
  ]
}

List submissions (authenticated)

GET /api/forms/{form_id}/submissions

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

Query parameters

Parameter	Type	Default	Description
filter	string	"inbox"	"inbox" (non-spam only), "spam" (spam only), or "all"
page	integer	1	Page number
page_size	integer	10	Results per page

Response (200)

{
  "data": [
    {
      "id": "eb72b858-4011-40dc-b707-8a3e67e13906",
      "data": {
        "name": "Alan Turing",
        "email": "alan@example.com",
        "message": "Hello"
      },
      "processing_status": "completed",
      "processing_reason": null,
      "spam_flag": false,
      "spam_confidence": null,
      "spam_reason": null,
      "original_language": null,
      "translated_data": null,
      "reply_status": "pending",
      "reply_content": null,
      "reply_reason": null,
      "replied_at": null,
      "created_at": "2026-03-01T12:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 42,
    "page_size": 10
  }
}

Get a submission

GET /api/forms/{form_id}/submissions/{id}

Returns the full submission including all processing fields (spam analysis, translations, smart reply data).

Delete a submission

DELETE /api/forms/{form_id}/submissions/{id}

Response 200: Returns the deleted submission.

Response 404:

{ "error": { "code": 404, "message": "Submission not found" } }