> ## 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.

# Commands

> Reference for every Paubox CLI command and global option, including send, schedule, status, config, receiving, and forms, with flags, examples, and exit codes.

## paubox send

Send a single HIPAA compliant email.

```bash theme={null}
paubox send --to <email> --subject <subject> [options]
```

### Flags

| Flag | Required | Description |
| :- | :- | :- |
| `--to <email>` | Yes | Recipient email address. Repeat for multiple recipients: `--to a@example.com --to b@example.com` |
| `--subject <text>` | Yes | Email subject line |
| `--html <html>` | One of `--html` or `--text` | HTML message body |
| `--text <text>` | One of `--html` or `--text` | Plain-text message body |
| `--from <email>` | No | Sender address. Defaults to `defaultFrom` from config if set. Must be on a verified Paubox domain |
| `--attachment <path>` | No | Path to a file to attach. Repeat for multiple attachments |

### Example

```bash theme={null}
paubox send \
  --to patient@example.com \
  --from provider@yourclinic.com \
  --subject "Your appointment summary" \
  --html "<p>See attached for your visit notes.</p>" \
  --attachment ./visit-notes.pdf
```

### Output

```
✓ Email sent. Tracking ID: abc123-def456
```

<Tip>
  Add `--json` to get machine-readable output instead of the human-readable success line. Useful for capturing the tracking ID in scripts and CI pipelines.
</Tip>

The underlying API call is documented in the [Email API · Messages](/email-api/messages) reference.

***

## paubox schedule

Manage scheduled emails: schedule, check status, reschedule, or cancel.

```bash theme={null}
paubox schedule <subcommand> [options]
```

### Subcommands

| Subcommand | Description |
| :- | :- |
| `paubox schedule send [options]` | Schedule an email for future delivery |
| `paubox schedule status <trackingId>` | Check status of a scheduled email |
| `paubox schedule reschedule <trackingId> --at <datetime>` | Change the scheduled time |
| `paubox schedule cancel <trackingId>` | Cancel a scheduled email |

### paubox schedule send

Schedule an email for future delivery.

```bash theme={null}
paubox schedule send --to <email> --subject <subject> --at <datetime> [options]
```

#### Flags

| Flag | Required | Description |
| :- | :- | :- |
| `--to <email>` | Yes | Recipient email address. Repeat for multiple recipients |
| `--subject <text>` | Yes | Email subject line |
| `--at <datetime>` | Yes | Scheduled send time in ISO 8601 format (e.g. `2025-12-25T15:00:00Z`) |
| `--html <html>` | One of `--html` or `--text` | HTML message body |
| `--text <text>` | One of `--html` or `--text` | Plain-text message body |
| `--from <email>` | No | Sender address. Defaults to `defaultFrom` from config if set |
| `--attachment <path>` | No | Path to a file to attach. Repeat for multiple attachments |

#### Example

```bash theme={null}
paubox schedule send \
  --to patient@example.com \
  --from provider@yourclinic.com \
  --subject "Appointment reminder" \
  --text "Your appointment is tomorrow at 10am." \
  --at 2025-12-25T15:00:00Z
```

#### Output

```
✓ Email scheduled for 2025-12-25T15:00:00Z. Tracking ID: abc123-def456
```

### paubox schedule status

Check the status of a scheduled email.

```bash theme={null}
paubox schedule status <trackingId>
```

#### Example

```bash theme={null}
paubox schedule status abc123-def456
```

#### Output

```
✓ Tracking ID: abc123-def456
State: pending
Scheduled at: 2025-12-25T15:00:00Z
```

### paubox schedule reschedule

Change the scheduled delivery time of a pending email.

```bash theme={null}
paubox schedule reschedule <trackingId> --at <datetime>
```

#### Flags

| Flag | Required | Description |
| :- | :- | :- |
| `--at <datetime>` | Yes | New scheduled send time in ISO 8601 format |

#### Example

```bash theme={null}
paubox schedule reschedule abc123-def456 --at 2025-12-26T10:00:00Z
```

#### Output

```
✓ Email rescheduled to 2025-12-26T10:00:00Z. Tracking ID: abc123-def456
```

### paubox schedule cancel

Cancel a scheduled email that has not yet been sent.

```bash theme={null}
paubox schedule cancel <trackingId>
```

#### Example

```bash theme={null}
paubox schedule cancel abc123-def456
```

#### Output

```
✓ Scheduled email cancelled. Tracking ID: abc123-def456
```

***

## paubox status

Check the delivery status of a sent message.

```bash theme={null}
paubox status <trackingId>
```

### Example

```bash theme={null}
paubox status abc123-def456
```

### Output

```
Recipient              Status      Delivered At          Opened  Opened At
patient@example.com    delivered   2026-05-24 09:14 UTC  Yes     2026-05-24 09:17 UTC
```

<Tip>
  Add `--json` to get machine-readable output. Useful for parsing status in scripts and CI pipelines.
</Tip>

The underlying API call is documented in the [Email API · Message receipt](/email-api/message-receipt) reference.

***

## paubox config

Manage CLI configuration stored in `~/.config/paubox/config.json`.

```bash theme={null}
paubox config <subcommand>
```

### Subcommands

| Subcommand | Description |
| :- | :- |
| `paubox config set <key> <value>` | Set a configuration value |
| `paubox config get <key>` | Print the current value for a key |
| `paubox config list` | Print all configuration keys and values |
| `paubox config reset` | Remove all configuration values |

### Supported keys

| Key | Description |
| :- | :- |
| `defaultFrom` | Default sender address used when `--from` is not passed to `paubox send` |

Additional keys may be added in future releases.

### Examples

```bash theme={null}
# Set a default sender
paubox config set defaultFrom provider@yourclinic.com

# Confirm it was saved
paubox config get defaultFrom
# provider@yourclinic.com

# List all config
paubox config list
# defaultFrom=provider@yourclinic.com

# Remove all config
paubox config reset
```

<Note>
  `paubox config` stores general settings only. API credentials are managed separately with `paubox auth` and stored in the OS keychain, not in `config.json`.
</Note>

***

## paubox receiving

Manage receiving domains, mailboxes, and inbound email.

```bash theme={null}
paubox receiving <resource> <subcommand> [options]
```

### paubox receiving domains

| Subcommand | Description |
| :- | :- |
| `paubox receiving domains list` | List all receiving domains |
| `paubox receiving domains create [--slug SLUG]` | Create a receiving domain |
| `paubox receiving domains get <id>` | Get a receiving domain |
| `paubox receiving domains delete <id>` | Delete a receiving domain |

#### Examples

```bash theme={null}
# Create a domain with a custom slug
paubox receiving domains create --slug support

# List all domains
paubox receiving domains list
```

### paubox receiving mailboxes

| Subcommand | Description |
| :- | :- |
| `paubox receiving mailboxes list <domainId>` | List mailboxes on a domain |
| `paubox receiving mailboxes create <domainId> --name NAME --password PASSWORD [--quota-bytes N]` | Create a mailbox |
| `paubox receiving mailboxes get <domainId> <mailboxId>` | Get a mailbox |
| `paubox receiving mailboxes delete <domainId> <mailboxId>` | Delete a mailbox |

#### Examples

```bash theme={null}
# Create a mailbox
paubox receiving mailboxes create 1 --name intake --password SecurePass123!

# List mailboxes on domain 1
paubox receiving mailboxes list 1
```

### paubox receiving emails

| Subcommand | Description |
| :- | :- |
| `paubox receiving emails list [--limit N] [--after CURSOR] [--before CURSOR]` | List received emails |
| `paubox receiving emails get <emailId>` | Get a received email |
| `paubox receiving emails attachment <emailId> <blobId> [--output FILE]` | Download an attachment |

#### Examples

```bash theme={null}
# List the 10 most recent emails
paubox receiving emails list --limit 10

# Get a specific email
paubox receiving emails get eaaaaab

# Download an attachment
paubox receiving emails attachment eaaaaab blob123 --output report.pdf
```

<Tip>
  Add `--json` to any receiving command for machine-readable output.
</Tip>

The underlying API calls are documented in the [Email API · Receiving](/email-api/receiving) reference.

***

## paubox forms

Fetch and submit Paubox Forms from the terminal. These commands hit the public Forms endpoints and do not require `paubox auth login`.

```bash theme={null}
paubox forms <subcommand> [options]
```

### Subcommands

| Subcommand | Description |
| :- | :- |
| `paubox forms get <formId>` | Fetch a form's metadata |
| `paubox forms submit <formId> [options]` | Submit a response (and optional attachments) to a form |

### paubox forms get

Fetch a form's metadata, including its title, description, and submission count.

```bash theme={null}
paubox forms get <formId>
```

#### Flags

| Flag | Required | Description |
| :- | :- | :- |
| `<formId>` | Yes | UUID of the form to fetch |
| `--json` | No | Return the raw API response object as JSON instead of the human-readable summary |

#### Example

```bash theme={null}
paubox forms get 550e8400-e29b-41d4-a716-446655440000
```

#### Output

```
Title:            Patient intake
Description:      Initial visit questionnaire
Active:           Yes
Submission count: 142
Created at:       2026-01-08 14:22 UTC
Updated at:       2026-05-19 09:41 UTC
```

<Tip>
  Add `--json` to get the raw API response object. Useful when you need the full Form payload, including `form_json`, `form_html`, and `form_css`, for rendering or validation.
</Tip>

The underlying API call is documented in the [Forms · Get form metadata](/forms/get-form) reference.

### paubox forms submit

Submit a response to a form, optionally with attachments.

```bash theme={null}
paubox forms submit <formId> [options]
```

#### Flags

| Flag | Required | Description |
| :- | :- | :- |
| `<formId>` | Yes | UUID of the form to submit a response to |
| `--data <key>=<value>` | One of `--data` or `--data-file` | Form field as a `key=value` pair. Repeat for multiple fields. Values may contain `=` |
| `--data-file <path>` | One of `--data` or `--data-file` | Path to a JSON file whose top-level string values are used as `form_data`. Merged with `--data`; `--data` takes precedence on key conflicts |
| `--attach <file>` | No | File to include as an attachment. Repeat for multiple attachments. Total request size must not exceed 250 MB |
| `--json` | No | Print machine-readable JSON output instead of the human-readable success line |

#### Examples

Submit with `--data` fields only:

```bash theme={null}
paubox forms submit 550e8400-e29b-41d4-a716-446655440000 \
  --data "first_name=Jane" \
  --data "last_name=Doe" \
  --data "email=jane@example.com"
```

Submit from a JSON file:

```bash theme={null}
paubox forms submit 550e8400-e29b-41d4-a716-446655440000 --data-file ./fields.json
```

Override individual fields from a JSON file:

```bash theme={null}
paubox forms submit 550e8400-e29b-41d4-a716-446655440000 \
  --data-file ./base.json \
  --data "field=override"
```

Submit with `--data` fields and an attachment:

```bash theme={null}
paubox forms submit 550e8400-e29b-41d4-a716-446655440000 \
  --data "name=Jane" \
  --attach /path/to/signed-consent.pdf
```

#### Output

```
✓ Form submitted successfully.
```

With `--json`:

```json theme={null}
{ "status": "ok", "formId": "550e8400-e29b-41d4-a716-446655440000" }
```

<Tip>
  Use `--json` when triggering submissions from CI pipelines or other automation that needs to confirm success programmatically.
</Tip>

The underlying API call is documented in the [Forms · Submit form response](/forms/submit-form) reference.

***

## Global options

These flags work with any command.

| Flag | Description |
| :- | :- |
| `--json` | Output results as JSON instead of human-readable text. Useful for scripting and CI pipelines |
| `-q`, `--quiet` | Suppress all non-essential output. Errors are still printed |
| `-v`, `--version` | Print the installed CLI version and exit |
| `--help` | Print usage information for a command and exit |

### Examples

```bash theme={null}
# Check version
paubox --version

# Get help for a specific command
paubox send --help

# Quiet mode: only print errors
paubox send --to a@example.com --subject "Hi" --text "Hello" --quiet
```

### Exit codes

The CLI exits with `0` on success and a non-zero code on failure. Use this in scripts and CI pipelines to detect errors:

```bash theme={null}
paubox send --to patient@example.com --subject "Hi" --text "Hello" || echo "Send failed"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.