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 schedule

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

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.

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

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.

paubox schedule status <trackingId>

Example

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.

paubox schedule reschedule <trackingId> --at <datetime>

Flags

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

Example

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.

paubox schedule cancel <trackingId>

Example

paubox schedule cancel abc123-def456

Output

✓ Scheduled email cancelled. Tracking ID: abc123-def456

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 receiving

Manage receiving domains, mailboxes, and inbound email.

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

# 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

# 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

# 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

Add --json to any receiving command for machine-readable output.

The underlying API calls are documented in the 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.

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 schedule

​Subcommands

​paubox schedule send

​Flags

​Example

​Output

​paubox schedule status

​Example

​Output

​paubox schedule reschedule

​Flags

​Example

​Output

​paubox schedule cancel

​Example

​Output

​paubox status

​Example

​Output

​paubox config

​Subcommands

​Supported keys

​Examples

​paubox receiving

​paubox receiving domains

​Examples

​paubox receiving mailboxes

​Examples

​paubox receiving emails

​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 schedule

Subcommands

paubox schedule send

Flags

Example

Output

paubox schedule status

Example

Output

paubox schedule reschedule

Flags

Example

Output

paubox schedule cancel

Example

Output

paubox status

Example

Output

paubox config

Subcommands

Supported keys

Examples

paubox receiving

paubox receiving domains

Examples

paubox receiving mailboxes

Examples

paubox receiving emails

Examples

paubox forms

Subcommands

paubox forms get

Flags

Example

Output

paubox forms submit

Flags

Examples

Output

Global options

Examples

Exit codes