> ## 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 Node.js SDK.

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

## Create the service

```javascript theme={null}
const pbMail       = require('paubox-node');
const formsService = pbMail.formService();
```

## Get a form

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

```javascript theme={null}
const form = await formsService.getForm('your-form-uuid');

console.log('Title:', form.title);
console.log('HTML:',  form.form_html);
```

Key fields in the response:

| Field              | 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            |

The Promise rejects with a 404 error if the form UUID is invalid.

## Submit a form

```javascript theme={null}
await formsService.submitForm('your-form-uuid', {
  first_name: 'Jane',
  last_name:  'Smith',
  email:      'jane@example.com'
});
// Resolves to null on success (HTTP 201)
```

### Submitting with file attachments

The maximum total request size is 250 MB.

```javascript theme={null}
const fs = require('fs');

const attachments = [
  {
    name:    'consent.pdf',
    content: fs.readFileSync('consent.pdf').toString('base64')
  }
];

await formsService.submitForm(
  'your-form-uuid',
  { first_name: 'Jane' },
  attachments
);
```

Each attachment is an object with two fields:

| Field     | Description                   |
| --------- | ----------------------------- |
| `name`    | File name including extension |
| `content` | Base64-encoded file content   |

## Error handling

```javascript theme={null}
try {
  const form = await formsService.getForm('your-form-uuid');
  await formsService.submitForm('your-form-uuid', formData);
} catch (err) {
  console.error('Forms error:', err.message);
}
```

The Promise rejects on HTTP 400 (bad request) and 404 (form not found).