pp-emailoctopus

What this skill does

<!-- 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:
   ```bash
   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):

```bash
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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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._

  ```bash
  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:

```bash
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

```bash
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

```bash
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

```bash
emailoctopus-pp-cli contacts dedupe --json
```

Lo