pp-sendgrid

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/productivity/sendgrid/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/". -->

# Twilio SendGrid — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `sendgrid-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 sendgrid --cli-only
   ```
2. Verify: `sendgrid-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/productivity/sendgrid/cmd/sendgrid-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 sendgrid-pp-cli for any SendGrid task an agent or operator wants to run from the terminal: transactional mail sends, suppression hygiene, contact list mirror, marketing campaign post-mortems, deliverability stats reporting, template management, and subuser rollups. It is the right choice when the workflow needs cross-endpoint joins (bounce investigations) or offline analysis (stats rollups, diffs) that the live API alone cannot produce.

## Unique Capabilities

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

### Local state that compounds

- **`suppression sync`** — Bidirectional sync between SendGrid suppressions and an external CSV/CRM source, with dry-run preview and unified schema across the four inconsistent suppression types.

  _When you need to reconcile SendGrid's suppression list with another system without writing custom glue code per suppression type._

  ```bash
  sendgrid-pp-cli suppression sync --from internal-suppressions.csv --apply --dry-run --json
  ```
- **`suppression diff`** — Three-way diff between the local SQLite mirror, live API, and an external CSV; shows adds, drops, and drift across the suppression universe.

  _When auditing CRM ↔ SendGrid drift before a cleanup pass or migration._

  ```bash
  sendgrid-pp-cli suppression diff bounces --against crm-export.csv --json
  ```
- **`stats rollup`** — Pulls flat windowed stats from the API, stores them in SQLite, and computes day/week/month rollups plus WoW/MoM deltas.

  _Use for trend reporting and weekly deliverability standups without paying for paid analytics._

  ```bash
  sendgrid-pp-cli stats rollup --by week --metric opens,clicks --window 90d --json
  ```
- **`templates diff`** — Side-by-side semantic diff of two template versions (HTML, plain text, subject, test data) with HTML-aware normalization.

  _Use during template review to see exactly what changed between draft versions._

  ```bash
  sendgrid-pp-cli templates diff d-abc123 v1 v2
  ```

### Pre-flight checks the API skips

- **`templates lint`** — Statically extracts {{handlebars}} from a template version and cross-checks them against a contact record or JSON payload, flagging missing or typo'd variables before send.

  _Use before any production send to catch silently-empty template variables that would otherwise ship as blanks._

  ```bash
  sendgrid-pp-cli templates lint d-abc123 --against '{"first_name":"Sam"}' --json
  ```

### Cross-endpoint joins

- **`bounce why`** — Joins suppressions, email activity, and stats locally to produce a narrative explaining why a specific address keeps bouncing.

  _When a customer reports they aren't getting emails and you need a fast root cause._

  ```bash
  sendgrid-pp-cli bounce why [email protected] --json
  ```
- **`subusers rollup`** — Fans out per-subuser stats pulls in parallel, caches them locally, and produces a single aggregated table for ESP operators managing tenant hierarchies.

  _Use for tenant-level deliverability reporting when you run subusers and need per-tenant numbers in one view._

  ```bash
  sendgrid-pp-cli subusers rollup --metric reputation,bounces --window 30d --json
  ```

### Rate-aware streaming

- **`activity tail`** — Streams Email Activity events with rate-limit-aware polling (respects the 6/min cap), local FTS, and filters by status/from/to.

  _Use during a deliverability incident to watch events as they happen without tripping the rate limit._

  ```bash
  sendgrid-pp-cli activity tail --filter status:bounce --json
  ```

## Command Reference

**access-settings** — Manage access settings

- `sendgrid-pp-cli access-settings add-ip-to-allow-list` — **This endpoint allows you to add one or more allowed IP addresses.** To allow one or more IP addresses, pass them...
- `sendgrid-pp-cli access-settings delete-allowed-ip` — **This endpoint allows you to remove a specific IP address from your list of allowed addresses.** When removing a...
- `sendgrid-pp-cli access-settings delete-allowed-ips` — **This endpoint allows you to remove one or more IP addresses from your list of allowed addresses.** To remove one...
- `sendgrid-pp-cli access-settings get-allowed-ip` — **This endpoint allows you to retreive a specific IP address that has been allowed to access your account.** You...
- `sendgrid-pp-cli access-settings list-access-activity` — **This endpoint allows you to retrieve a list of all of the IP addresses that recently attempted to access your...
- `sendgrid-pp-cli access-settings list-allowed-ip` — **This endpoint allows you to retrieve a list of IP addresses that are currently allowed to access your account.**...

**alerts** — Twilio SendGrid Alerts API.

- `sendgrid-pp-cli alerts create` — **This endpoint allows you to create a new alert.**
- `sendgrid-pp-cli alerts delete` — **This endpoint allows you to delete an alert.**
- `sendgrid-pp-cli alerts get` — **This endpoint allows you to retrieve a specific alert.**
- `sendgrid-pp-cli alerts list` — **This endpoint allows you to retrieve all of your alerts.**
- `sendgrid-pp-cli alerts update` — **This endpoint allows you to update an alert.**

**api-keys** — Twilio SendGrid API Keys API.

- `sendgrid-pp-cli api-keys create` — **This endpoint allows you to create a new API Key for the user.** To create your initial SendGrid API Key, you...
- `sendgrid-pp-cli api-keys delete` — **This endpoint allows you to revoke an existing API Key using an `api_key_id`** Authentications using a revoked API...
- `sendgrid-pp-cli api-keys get` — **This endpoint allows you to retrieve a single API key using an `api_key_id`.** The endpoint will return a key's...
- `sendgrid-pp-cli api-keys list` — **This endpoint allows you to retrieve all API Keys that belong to the authenticated user.** A successful response...
- `sendgrid-pp-cli api-keys update` — **This endpoint allows you to update the name and scopes of a given API key.** You must pass this endpoint a JSON...
- `sendgrid-pp-cli api-keys update-name` — **This endpoint allows you to update the name of an existing API Key.** You must pass this endpoint a JSON request...

**asm** — Manage asm

- `sendgrid-pp-cli asm add-suppression-to-group` — **This endpoint allows you to add email addresses to an unsubscribe group.** If you attempt to add suppressions to a...
- `sendgrid-pp-cli asm creat-group` — **This endpoint allows you to create a new suppression group.** To add an email address to the suppression group,...
- `sendgrid-pp-cli asm create-global-suppression` — **This endpoint allows you to add one