> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms client

> Retrieve Paubox Form schemas and submit form responses using the Rust SDK.

The Forms client does not require API credentials. Forms are identified by a UUID that you obtain from the Paubox dashboard.

## Creating a client

**Standalone** (creates its own HTTP connection pool):

```rust theme={null}
use paubox::FormsClient;

let client = FormsClient::new();
```

**Shared connection pool** (reuses the HTTP client from an existing `PauboxClient`):

```rust theme={null}
let forms = email_client.forms();
```

## Get a form

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

```rust theme={null}
let form = client.get_form("your-form-uuid").await?;

println!("Title: {}", form.title);
if let Some(html) = &form.form_html {
    println!("HTML: {}", html);
}
```

`Form` fields:

| Field              | Type                        | Description                               |
| ------------------ | --------------------------- | ----------------------------------------- |
| `title`            | `String`                    | Display name of the form                  |
| `form_json`        | `Option<serde_json::Value>` | Parsed field schema                       |
| `form_html`        | `Option<String>`            | Rendered HTML for embedding               |
| `form_css`         | `Option<String>`            | Associated stylesheet                     |
| `active`           | `bool`                      | Whether the form is accepting submissions |
| `submission_count` | `u64`                       | Number of submissions received            |

## Submit a form

Build a `FormSubmission` and call `submit_form`:

```rust theme={null}
use paubox::FormSubmission;
use serde_json::json;

let submission = FormSubmission::builder()
    .form_data(json!({
        "first_name": "Jane",
        "last_name":  "Smith",
        "email":      "jane@example.com"
    }))
    .build()?;

client.submit_form("your-form-uuid", &submission).await?;
```

`submit_form` returns `Ok(())` on success (HTTP 201).

### Submitting with file attachments

The maximum total request size is 250 MB. `FormAttachment::from_bytes` base64-encodes automatically:

```rust theme={null}
use paubox::{FormAttachment, FormSubmission};
use std::fs;

let data = fs::read("consent.pdf")?;
let attachment = FormAttachment::from_bytes("consent.pdf", &data);

let submission = FormSubmission::builder()
    .form_data(json!({ "first_name": "Jane" }))
    .attachment(attachment)
    .build()?;

client.submit_form("your-form-uuid", &submission).await?;
```

If you already have base64-encoded content:

```rust theme={null}
let attachment = FormAttachment::from_base64("consent.pdf", encoded_string);
```

## Error handling

```rust theme={null}
use paubox::PauboxError;

match client.get_form("your-form-uuid").await {
    Ok(form) => println!("Form: {}", form.title),
    Err(PauboxError::Http { status, body }) => {
        eprintln!("HTTP {}: {}", status, body);
    }
    Err(e) => eprintln!("Error: {}", e),
}
```