pp-emailoctopus

name: pp-emailoctopus description: "Every EmailOctopus v2 endpoint, plus the cross-list joins, churn diffs, and rate-budgeted bulk operations the API... Trigger phrases: manage my EmailOctopus list, sync subscribers to EmailOctopus, EmailOctopus campaign report, find cold subscribers, dedupe my email lists, use emailoctopus, run emailoctopus." author: "Trevin Chow" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - emailoctopus-pp-cli

EmailOctopus — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the emailoctopus-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install emailoctopus --cli-only
   

2. Verify: emailoctopus-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

go install github.com/mvanhorn/printing-press-library/library/marketing/emailoctopus/cmd/emailoctopus-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

When to Use This CLI

Use this CLI when an agent or operator needs the full EmailOctopus v2 surface — lists, contacts, tags, custom fields, campaign reports, and automation triggers — plus the local-join queries the hosted API can't answer (cross-list duplicates, per-contact engagement scoring, list churn since the last snapshot, tag set-algebra). Especially valuable for indie newsletter operators, small-SaaS growth engineers, and agencies running many client lists, since it works offline once synced and paces all mutations under the documented 10 req/sec rate limit.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Local joins the API can't do

• contacts engagement — Score every contact by opens, clicks, and inactive-since across all campaigns. The API has no engagement-history endpoint; we synthesize it locally.

  Pick this when an agent needs to find cold subscribers, build a reactivation cohort, or score engagement without paginating every campaign report by hand.

  emailoctopus-pp-cli contacts engagement --list <list_id> --inactive-since 90d --json
  

• contacts dedupe — Find contacts that appear on multiple lists in the account, optionally consolidating them onto one canonical list.

  Pick this when an agent needs to clean up subscriber duplication, audit list sprawl, or plan a merge across multiple lists.

  emailoctopus-pp-cli contacts dedupe --json
  

• tags intersect — Find contacts matching boolean combinations of tags: --has trial-started --not activated returns the trial cohort that hasn't converted.

  Pick this when an agent needs to segment subscribers by tag combinations for targeted outreach, churn reactivation, or audience reporting.

  emailoctopus-pp-cli tags intersect --list <list_id> --has trial-started --not activated --json
  

Workflow accelerators

• campaigns digest — One-shot campaign report combining summary, top-N links, contact-level breakdown, and per-domain opens — rendered for terminal or Markdown paste.

  Pick this when an agent needs to summarize a campaign's results for a stakeholder doc without screen-scraping the EmailOctopus dashboard.

  emailoctopus-pp-cli campaigns digest <campaign_id> --md
  

• contacts sync-csv — Push a CSV into EmailOctopus with mapped fields and tags. Dry-runs the diff against the local store first, then chunks into batch-upsert calls paced under the rate limit.

  Pick this when an agent needs to atomically sync a CSV of contacts with tag/field mapping and pre-flight the change before applying it.

  emailoctopus-pp-cli contacts sync-csv ./subscribers.csv --list <list_id> --map email=Email,tag.plan=Plan --dry-run
  

Local snapshots over time

• lists diff — Show contacts touched in this list since a relative time. Surfaces the change-set the API can't return — useful for incremental syncs, audit logs, or alerting on recent activity.

  Pick this when an agent needs to see which contacts were touched in the last hour/day/week or run an incremental change-detection workflow.

  emailoctopus-pp-cli lists diff <list_id> --since yesterday --json
  

Mutation safety

• contacts bulk-delete — Delete many contacts matching a local predicate, paced under the 10/sec API limit with a resumable progress file.

  Pick this when an agent needs to clean up unsubscribed, bounced, or stale contacts in bulk without hitting 429s or losing progress mid-run.

  emailoctopus-pp-cli contacts bulk-delete --list <list_id> --where 'status=unsubscribed' --rate 8 --dry-run
  

• automations trigger-batch — Queue an automation for many contacts from stdin or CSV, paced under the rate limit with retry on 429.

  Pick this when an agent needs to start an automation for a batch of contacts (trial-ending cohort, plan-upgrade celebration) without writing loop+backoff boilerplate.

  cat trial-ending.csv | emailoctopus-pp-cli automations trigger-batch <automation_id> --stdin
  

Command Reference

automations — An automation is a sequence of automated steps triggered by an event, such as when a contact subscribes to a list or is tagged. Automations allow you to automatically send emails, update fields, apply tags and more.

campaigns — A campaign is generally used to send a one-off, timely email to some or all of your subscribers. For example you may use a campaign to send the latest edition of your weekly newsletter, or to announce a new feature in your product.

• emailoctopus-pp-cli campaigns get — Get all campaigns
• emailoctopus-pp-cli campaigns id-get — Get campaign

lists — A list is a collection of contacts. Every one of your contacts will exist inside a list. The majority of our users only require one list, but multiple lists can be created and configured with different fields and tags in order to organise distinct groups of contacts.

• emailoctopus-pp-cli lists get — Get all lists
• emailoctopus-pp-cli lists id-delete — Delete a list
• emailoctopus-pp-cli lists id-get — Get list
• emailoctopus-pp-cli lists id-put — Update list
• emailoctopus-pp-cli lists post — Create list

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

emailoctopus-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Recipes

Find cold subscribers across a list

emailoctopus-pp-cli contacts engagement --list <list_id> --inactive-since 90d --json --select email_address,last_engaged_at,opens,clicks

Joins synced contacts with all campaign contact-reports to surface anyone who hasn't opened or clicked in 90 days. The --select narrows the response to just the fields an agent needs, dropping the ~10KB of nested per-campaign detail.

Generate a paste-ready campaign report

emailoctopus-pp-cli campaigns digest 071f24b2-51cd-11f1-a3ce-11fd783017da --md

One command renders summary metrics, top-clicked links, per-domain opens, and unsubscribe breakdown as Markdown — paste straight into Notion or a stakeholder doc.

Find contacts on more than one list

emailoctopus-pp-cli contacts dedupe --json

Local SQL groups contacts by lowercased email across every synced list, returning the duplicates with their list memberships. Useful before consolidating lists or auditing subscriber sprawl.

Segment by tag set-algebra

emailoctopus-pp-cli tags intersect --list <list_id> --has trial-started --not activated --json

Returns the contacts tagged trial-started but not activated — the cohort that's still in trial but hasn't converted. EmailOctopus has no native segmentation API.

Bulk delete with a safety net

emailoctopus-pp-cli contacts bulk-delete --where status=unsubscribed --list c81c21ca-51cc-11f1-ad3e-ffeba75576ac --rate 8 --dry-run

Resolves the predicate against the local store and shows what would be deleted. Drop --dry-run to actually delete, paced at 8 req/sec under the 10/sec API limit, with a resumable progress file in case the run is interrupted.

Diff a list to see what changed

emailoctopus-pp-cli lists diff c81c21ca-51cc-11f1-ad3e-ffeba75576ac --since 1d --json

Returns contacts in the list whose local synced_at timestamp is within the requested window. Useful for incremental change detection — the API has no native change feed.

Auth Setup

Generate a v2 key at https://api.emailoctopus.com/developer/api-keys/create and export it as EMAILOCTOPUS_API_KEY. Keys created before October 2024 are v1-only and will return 401 against the v2 API — regenerate if you see auth errors.

Alternatively, persist the key without an env var: emailoctopus-pp-cli auth set-token saves it to the config file; emailoctopus-pp-cli auth status shows where the active key was loaded from; emailoctopus-pp-cli auth logout clears it.

Run emailoctopus-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  emailoctopus-pp-cli campaigns get --agent --select id,name,status
  

• Previewable — --dry-run shows the request without sending

• Offline-friendly — sync/search commands can use the local SQLite store when available

• Non-interactive — never prompts, every input is a flag

• Explicit retries — use --idempotent only when an already-existing create should count as success, and --ignore-missing only when a missing delete target should count as success

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

emailoctopus-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
emailoctopus-pp-cli feedback --stdin < notes.txt
emailoctopus-pp-cli feedback list --json --limit 10

Entries are stored locally at ~/.emailoctopus-pp-cli/feedback.jsonl. They are never POSTed unless EMAILOCTOPUS_FEEDBACK_ENDPOINT is set AND either --send is passed or EMAILOCTOPUS_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.

emailoctopus-pp-cli profile save briefing --json
emailoctopus-pp-cli --profile briefing campaigns get
emailoctopus-pp-cli profile list --json
emailoctopus-pp-cli profile show briefing
emailoctopus-pp-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help → show emailoctopus-pp-cli --help output
2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:

claude mcp add emailoctopus-pp-mcp -- emailoctopus-pp-mcp

Verify: claude mcp list

Direct Use

1. Check if installed: which emailoctopus-pp-cli If not found, offer to install (see Prerequisites at the top of this skill).
2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
3. Execute with the --agent flag:

   emailoctopus-pp-cli <command> [subcommand] [args] --agent
   

4. If ambiguous, drill into subcommand help: emailoctopus-pp-cli <command> --help.