Rails SDK forms client

get_form and submit_form do not require API credentials. Forms are identified by a UUID that you obtain from the Paubox dashboard. The form management methods require a scoped API key; see Manage forms.

Create a client

client = PauboxRails::Forms.client

PauboxRails::Forms.client returns a new PauboxRails::Forms::Client instance.

Get a form

Retrieve a form’s metadata, field schema, and rendered HTML/CSS:

form = client.get_form("your-form-uuid")

puts form["title"]
puts form["form_html"]
puts form["form_json"].inspect

The return value is a Hash with the following keys:

Key	Description
`"title"`	Display name of the form
`"form_json"`	Parsed field schema
`"form_html"`	Rendered HTML for embedding
`"form_css"`	Associated stylesheet
`"active"`	Whether the form is accepting submissions
`"submission_count"`	Number of submissions received

get_form raises PauboxRails::Forms::NotFoundError if no form exists for the ID (HTTP 404).

Submit a form

result = client.submit_form(
  "your-form-uuid",
  form_data: {
    "first_name" => "Jane",
    "last_name"  => "Smith",
    "email"      => "jane@example.com"
  }
)
# result => true

submit_form returns true on a successful submission (HTTP 201).

Submitting with file attachments

The maximum total request size is 250 MB.

require "base64"

encoded = Base64.strict_encode64(File.read(Rails.root.join("tmp/consent.pdf")))

result = client.submit_form(
  "your-form-uuid",
  form_data: { "first_name" => "Jane" },
  attachments: [
    { name: "consent.pdf", content: encoded }
  ]
)

Each attachment is a Hash with two keys:

Key	Description
`:name`	File name including extension
`:content`	Base64-encoded file content

Manage forms

The management methods require a scoped API key with the forms scope, passed as api_key: or set as PAUBOX_FORMS_API_KEY. It can be the same key as the Email API key if that key also has the forms scope.

client = PauboxRails::Forms.client(api_key: ENV['PAUBOX_FORMS_API_KEY'])

result = client.list_forms(customer_id: 12345)

Available methods: get_form_details, list_forms (requires customer_id:), create_form, update_form, archive_form, unarchive_form, copy_form, form_stats, list_submissions, submissions_csv, and submission_pdf. Calling one without a key raises PauboxRails::Forms::MissingApiKeyError.

Error handling

All Forms errors inherit from PauboxRails::Forms::Error: NotFoundError (HTTP 404), BadRequestError (HTTP 400 or 422), UnauthorizedError (HTTP 401), ForbiddenError (HTTP 403), and MissingApiKeyError. An empty ID, or a non-UUID form or submission ID in the URL of a management method (every method except copy_form), raises ArgumentError before a request is made.

begin
  form   = client.get_form("your-form-uuid")
  result = client.submit_form("your-form-uuid", form_data: data)
rescue PauboxRails::Forms::NotFoundError
  # Form UUID not found (HTTP 404)
rescue PauboxRails::Forms::BadRequestError
  # Malformed request (HTTP 400 or 422)
rescue PauboxRails::Forms::Error => e
  # Any other Forms API error
  Rails.logger.error("Forms error: #{e.message}")
end

Get started

Email API

Migrate to Paubox

Marketing API

MCP Server

SDKs

CLI

Forms API

Create a client

Get a form

Submit a form

Submitting with file attachments

Manage forms

Error handling

​Create a client

​Get a form

​Submit a form

​Submitting with file attachments

​Manage forms

​Error handling

Create a client

Get a form

Submit a form

Submitting with file attachments

Manage forms

Error handling