SendFox CLI

Operate SendFox contacts, lists, campaign reads, audience hygiene, CSV reconciliation, launch checklists, signup-form handoffs, webhook setup packets, and public API capability checks from the terminal.

Quick Start

1. Install

See Install above.

2. Set Up Credentials

Create a SendFox personal access token at https://sendfox.com/account/oauth, then store it:

sendfox-pp-cli auth set-token YOUR_TOKEN_HERE

Or set it via environment variable:

export SENDFOX_API_TOKEN="your-token-here"

3. Verify Setup

sendfox-pp-cli doctor

This checks your configuration and credentials.

4. Try Your First Command

sendfox-pp-cli workflow account-snapshot --agent

Usage

Run sendfox-pp-cli --help for the full command reference and flag list.

Commands

capabilities

Documented public API support matrix

• sendfox-pp-cli capabilities - Show which SendFox resources support list/get/create/update/delete and where dashboard handoffs are required

campaigns

Campaign reads

• sendfox-pp-cli campaigns get - Get campaign by ID
• sendfox-pp-cli campaigns list - List campaigns

contacts

Contacts and subscription state

• sendfox-pp-cli contacts create - Create a contact
• sendfox-pp-cli contacts get - Get a contact by ID
• sendfox-pp-cli contacts list - List contacts or find a contact by email
• sendfox-pp-cli contacts onboard - Create a contact and attach list memberships in one automation-aware flow
• sendfox-pp-cli contacts import-csv - Bulk-create contacts from CSV behind a dry-run/--yes safety gate
• sendfox-pp-cli contacts audit-csv - Validate subscriber CSVs for invalid and duplicate emails before any mutation
• sendfox-pp-cli contacts reconcile-csv - Compare a CSV against live contacts and emit create/skip actions

forms

Generate SendFox integration assets

• sendfox-pp-cli forms generate - Generate a self-contained HTML signup form and server-proxy handoff

lists

Contact lists

• sendfox-pp-cli lists create - Create a contact list
• sendfox-pp-cli lists get - Get a contact list by ID
• sendfox-pp-cli lists list-lists - List contact lists

workflow

Compound SendFox workflows for agents

• sendfox-pp-cli workflow account-snapshot - Summarize account, list, contact, and campaign state
• sendfox-pp-cli workflow audience-map - Map contacts to lists and surface segmentation gaps
• sendfox-pp-cli workflow campaign-digest - Summarize campaign count, status mix, and recency
• sendfox-pp-cli workflow hygiene-report - Find duplicate emails, invalid emails, status mix, and list-membership gaps
• sendfox-pp-cli workflow launch-plan - Generate a safe SendFox list-launch checklist and exact next CLI/dashboard steps

webhooks

Generate SendFox webhook/dashboard handoffs

• sendfox-pp-cli webhooks handoff - Generate dashboard setup and handler-contract packets for SendFox webhook receivers

me

Manage me

• sendfox-pp-cli me - Get authenticated user

unsubscribe

Manage unsubscribe

• sendfox-pp-cli unsubscribe - Unsubscribe a contact by email

Unique Features

• capabilities — machine-readable API support matrix, so agents do not invent unsupported SendFox campaign/webhook write calls.
• workflow account-snapshot — one read-only SendFox operating packet across account, lists, contacts, and campaigns. Use this before planning campaigns or auditing account state.
• workflow audience-map — list membership map with contacts that are not attached to any list, useful for cleanup and automation-trigger checks.
• workflow campaign-digest — status-count and recent-campaign digest without hand-rolling campaign list parsing.
• workflow hygiene-report — live hygiene report for duplicate/invalid emails, contact status mix, and contacts without lists.
• workflow launch-plan — safe launch checklist that validates the list, emits exact next commands, and explicitly keeps campaign creation/sending in the dashboard because the public docs expose campaign reads only.
• contacts audit-csv — preflight CSV validation for duplicate and invalid subscriber emails before any SendFox mutation.
• contacts reconcile-csv — compares a CSV to live contacts, then returns create/skip actions for agent review.
• contacts onboard — one command to create a subscriber and attach list IDs, with --dry-run --agent showing the exact request that may trigger list automations.
• contacts import-csv — guarded bulk importer for email,first_name,last_name CSVs; live runs require --yes after dry-run review.
• forms generate — creates an embeddable HTML signup form plus explicit server-proxy note so browser code never leaks the bearer token.
• webhooks handoff — dashboard setup packet and receiver contract for webhook installs, without pretending there is public webhook CRUD.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
sendfox-pp-cli campaigns list

# JSON for scripting and agents
sendfox-pp-cli campaigns list --json

# Filter to specific fields
sendfox-pp-cli campaigns list --json --select id,name,status

# Dry run — show the request without sending
sendfox-pp-cli campaigns list --dry-run

# Agent mode — JSON + compact + no prompts in one flag
sendfox-pp-cli campaigns list --agent

Agent Usage

This CLI is designed for AI agent consumption:

• Non-interactive - never prompts, every input is a flag
• Pipeable - --json output to stdout, errors to stderr
• Filterable - --select id,name returns only fields you need
• Previewable - --dry-run shows the request without sending
• Explicit retries - add --idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
• Confirmable - --yes for explicit confirmation of destructive actions
• Piped input - write commands can accept structured input when their help lists --stdin
• Offline-friendly - sync/search commands can use the local SQLite store when available
• Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

sendfox-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/sendfox-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
SENDFOX_API_TOKEN	per_call	Yes	Preferred SendFox personal access token env var.
SENDFOX_BEARER_AUTH	per_call	No	Backward-compatible alias for SENDFOX_API_TOKEN.

agentcookie (optional)

If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, sendfox-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.

Troubleshooting

Authentication errors (exit code 4)

• Run sendfox-pp-cli doctor to check credentials
• Verify the environment variable is set: echo $SENDFOX_API_TOKEN Not found errors (exit code 3)
• Check the resource ID is correct
• Run the list command to see available items

---

Generated by CLI Printing Press