Commands - Paubox API Docs

paubox send

Send a single HIPAA compliant email.

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

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

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.

The underlying API call is documented in the Email API · Messages reference.

paubox status

Check the delivery status of a sent message.

paubox status <trackingId>

Example

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

Add --json to get machine-readable output. Useful for parsing status in scripts and CI pipelines.

The underlying API call is documented in the Email API · Message receipt reference.

paubox config

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

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

# 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

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

paubox forms

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

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.

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

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

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.

The underlying API call is documented in the Forms · Get form metadata reference.

paubox forms submit

Submit a response to a form, optionally with attachments.

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:

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:

paubox forms submit 550e8400-e29b-41d4-a716-446655440000 --data-file ./fields.json

Override individual fields from a JSON file:

paubox forms submit 550e8400-e29b-41d4-a716-446655440000 \
  --data-file ./base.json \
  --data "field=override"

Submit with --data fields and an attachment:

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

Output

✓ Form submitted successfully.

With --json:

{ "status": "ok", "formId": "550e8400-e29b-41d4-a716-446655440000" }

Use --json when triggering submissions from CI pipelines or other automation that needs to confirm success programmatically.

The underlying API call is documented in the Forms · Submit form response 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

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

paubox send --to patient@example.com --subject "Hi" --text "Hello" || echo "Send failed"

​paubox send

​Flags

​Example

​Output

​paubox status

​Example

​Output

​paubox config

​Subcommands

​Supported keys

​Examples

​paubox forms

​Subcommands

​paubox forms get

​Flags

​Example

​Output

​paubox forms submit

​Flags

​Examples

​Output

​Global options

​Examples

​Exit codes

paubox send

Flags

Example

Output

paubox status

Example

Output

paubox config

Subcommands

Supported keys

Examples

paubox forms

Subcommands

paubox forms get

Flags

Example

Output

paubox forms submit

Flags

Examples

Output

Global options

Examples

Exit codes