Pp Emailoctopus

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/marketing/emailoctopus/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

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