--- name: pp-sendgrid description: "Every Twilio SendGrid endpoint, plus offline suppression diffs, stats time-series rollups, and a template-variable... Trigger phrases: `send transactional mail`, `manage SendGrid suppressions`, `audit SendGrid bounces`, `SendGrid templates lint`, `SendGrid stats rollup`, `use sendgrid`, `run sendgrid`." author: "Nathan Kettles" license: "Apache-2.0" argument-hint: " [args] | install cli|mcp" allowed-tools: "Read Bash" metadata: openclaw: requires: bins: - sendgrid-pp-cli --- # 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.6 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 user@example.com --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 or more email addresses to the global suppressions group.** - `sendgrid-pp-cli asm delete-global-suppression` — **This endpoint allows you to remove an email address from the global suppressions group.** Deleting a suppression... - `sendgrid-pp-cli asm delete-group` — **This endpoint allows you to delete a suppression group.** If a recipient uses the 'one-click unsubscribe' option... - `sendgrid-pp-cli asm delete-suppression-from-group` — **This endpoint allows you to remove a suppressed email address from the given suppression group.** Removing an... - `sendgrid-pp-cli asm get-global-suppression` — **This endpoint allows you to retrieve a global suppression. You can also use this endpoint to confirm if an email... - `sendgrid-pp-cli asm get-group` — **This endpoint allows you to retrieve a single suppression group.** - `sendgrid-pp-cli asm get-suppression` — **This endpoint returns a list of all groups from which the given email address has been unsubscribed.** - `sendgrid-pp-cli asm list-group` — **This endpoint allows you to retrieve a list of all suppression groups created by this user.** This endpoint can... - `sendgrid-pp-cli asm list-suppression` — **This endpoint allows you to retrieve a list of all suppressions.** - `sendgrid-pp-cli asm list-suppression-from-group` — **This endpoint allows you to retrieve all suppressed email addresses belonging to the given group.** - `sendgrid-pp-cli asm search-suppression-from-group` — **This endpoint allows you to search a suppression group for multiple suppressions.** When given a list of email... - `sendgrid-pp-cli asm update-group` — **This endpoint allows you to update or change a suppression group.** **browsers** — Manage browsers - `sendgrid-pp-cli browsers` — **This endpoint allows you to retrieve your email statistics segmented by browser type.** **We only store up to 7... **campaigns** — Manage campaigns - `sendgrid-pp-cli campaigns create` — **This endpoint allows you to create a campaign.** In order to send or schedule the campaign, you will be required... - `sendgrid-pp-cli campaigns delete` — **This endpoint allows you to delete a specific campaign.** - `sendgrid-pp-cli campaigns get` — **This endpoint allows you to retrieve a specific campaign.** - `sendgrid-pp-cli campaigns list` — **This endpoint allows you to retrieve a paginated list of all of your campaigns.** Returns campaigns in reverse... - `sendgrid-pp-cli campaigns update` — **This endpoint allows you to update a specific campaign.** This is especially useful if you only set up the... **categories** — Twilio SendGrid Category Stats API - `sendgrid-pp-cli categories list-category` — **This endpoint allows you to retrieve a paginated list of all of your categories.** You can use the `limit` query... - `sendgrid-pp-cli categories list-category-stat` — **This endpoint allows you to retrieve all of your email statistics for each of your categories.** If you do not... - `sendgrid-pp-cli categories list-category-stat-sum` — **This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date... **clients** — Manage clients - `sendgrid-pp-cli clients` — **This endpoint allows you to retrieve your email statistics segmented by client type.** **We only store up to 7... **contactdb** — Manage contactdb - `sendgrid-pp-cli contactdb add-recipient` — **This endpoint allows you to add a Marketing Campaigns recipient.** You can add custom field data as a parameter on... - `sendgrid-pp-cli contactdb add-recipient-to-contact-db-list` — **This endpoint allows you to add a single recipient to a list.** - `sendgrid-pp-cli contactdb add-recipients-to-contact-db-list` — **This endpoint allows you to add multiple recipients to a list.** Adds existing recipients to a list, passing in... - `sendgrid-pp-cli contactdb create-contact-db-list` — **This endpoint allows you to create a list for your recipients.** - `sendgrid-pp-cli contactdb create-custom-field` — **This endpoint allows you to create a custom field.** **You can create up to 120 custom fields.** - `sendgrid-pp-cli contactdb create-segment` — **This endpoint allows you to create a new segment.** Valid operators for create and update depend on the type of... - `sendgrid-pp-cli contactdb delete-contact-db-list` — **This endpoint allows you to delete a specific recipient list with the given ID.** - `sendgrid-pp-cli contactdb delete-contact-db-lists` — **This endpoint allows you to delete multiple recipient lists.** - `sendgrid-pp-cli contactdb delete-custom-field` — **This endpoint allows you to delete a custom field by ID.** - `sendgrid-pp-cli contactdb delete-recipient` — **This endpoint allows you to delete a single recipient with the given ID from your contact database.** > Use this... - `sendgrid-pp-cli contactdb delete-recipient-from-contact-db-list` — **This endpoint allows you to delete a single recipient from a list.** - `sendgrid-pp-cli contactdb delete-recipients` — **This endpoint allows you to deletes one or more recipients.** The body of an API call to this endpoint must... - `sendgrid-pp-cli contactdb delete-segment` — **This endpoint allows you to delete a segment from your recipients database.** You also have the option to delete... - `sendgrid-pp-cli contactdb export-recipient` — **Use this endpoint to export lists or segments of recipients**. If you would just like to have a link to the... - `sendgrid-pp-cli contactdb get-billable` — **This endpoint allows you to retrieve the number of Marketing Campaigns recipients that you will be billed for.**... - `sendgrid-pp-cli contactdb get-contact-db-list` — **This endpoint allows you to retrieve a single recipient list.** - `sendgrid-pp-cli contactdb get-custom-field` — **This endpoint allows you to retrieve a custom field by ID.** - `sendgrid-pp-cli contactdb get-export-recipient` — **This endpoint can be used to check the status of a recipient export job**. To use this call, you will need the... - `sendgrid-pp-cli contactdb get-recipient` — **This endpoint allows you to retrieve a single recipient by ID from your contact database.** - `sendgrid-pp-cli contactdb get-recipient-list` — **This endpoint allows you to retrieve the lists that a given recipient belongs to.** Each recipient can be on many... - `sendgrid-pp-cli contactdb get-segment` — **This endpoint allows you to retrieve a single segment with the given ID.** - `sendgrid-pp-cli contactdb list-contact-db-list` — **This endpoint allows you to retrieve all of your recipient lists. If you don't have any lists, an empty array will... - `sendgrid-pp-cli contactdb list-custom-field` — **This endpoint allows you to retrieve all custom fields.** - `sendgrid-pp-cli contactdb list-export-recipient` — **Use this endpoint to retrieve details of all current exported jobs**. It will return an array of objects, each of... - `sendgrid-pp-cli contactdb list-recipient` — **This endpoint allows you to retrieve all of your Marketing Campaigns recipients.** Batch deletion of a page makes... - `sendgrid-pp-cli contactdb list-recipient-count` — **This endpoint allows you to retrieve the total number of Marketing Campaigns recipients.** - `sendgrid-pp-cli contactdb list-recipient-for-segment` — **This endpoint allows you to retrieve all of the recipients in a segment with the given ID.** - `sendgrid-pp-cli contactdb list-recipients-from-contact-db-list` — **This endpoint allows you to retrieve all recipients on the list with the given ID.** - `sendgrid-pp-cli contactdb list-reserved-field` — **This endpoint allows you to list all fields that are reserved and can't be used for custom field names.** - `sendgrid-pp-cli contactdb list-search-recipient` — **This endpoint allows you to perform a search on all of your Marketing Campaigns recipients.** field_name: * is a... - `sendgrid-pp-cli contactdb list-segment` — **This endpoint allows you to retrieve all of your segments.** - `sendgrid-pp-cli contactdb list-status` — **This endpoint allows you to check the upload status of a Marketing Campaigns recipient.** - `sendgrid-pp-cli contactdb search-recipient` — Search using segment conditions without actually creating a segment. Body contains a JSON object with `conditions`,... - `sendgrid-pp-cli contactdb update-contact-db-list` — **This endpoint allows you to update the name of one of your recipient lists.** - `sendgrid-pp-cli contactdb update-recipient` — **This endpoint allows you to update one or more recipients.** The body of an API call to this endpoint must include... - `sendgrid-pp-cli contactdb update-segment` — **This endpoint allows you to update a segment.** **designs** — Twilio SendGrid Marketing Campaigns Designs API - `sendgrid-pp-cli designs create` — **This endpoint allows you to create a new design**. You can add a new design by passing data, including a string of... - `sendgrid-pp-cli designs delete` — **This endpoint allows you to delete a single design**. Be sure to check the ID of the design you intend to delete... - `sendgrid-pp-cli designs duplicate` — **This endpoint allows you to duplicate one of your existing designs**. Modifying an existing design is often the... - `sendgrid-pp-cli designs duplicate-pre-built` — **This endpoint allows you to duplicate one of the pre-built Twilio SendGrid designs**. Like duplicating one of your... - `sendgrid-pp-cli designs get` — **This endpoint allows you to retrieve a single design**. A GET request to `/designs/{id}` will retrieve details... - `sendgrid-pp-cli designs get-pre-built` — **This endpoint allows you to retrieve a single pre-built design**. A GET request to `/designs/pre-builts/{id}` will... - `sendgrid-pp-cli designs list` — **This endpoint allows you to retrieve a list of designs already stored in your Design Library**. A GET request to... - `sendgrid-pp-cli designs list-pre-built` — **This endpoint allows you to retrieve a list of pre-built designs provided by Twilio SendGrid**. Unlike the... - `sendgrid-pp-cli designs update` — **This endpoint allows you to edit a design**. The Design API supports PATCH requests, which allow you to make... **devices** — Manage devices - `sendgrid-pp-cli devices` — **This endpoint allows you to retrieve your email statistics segmented by the device type.** **We only store up to 7... **engagementquality** — Manage engagementquality - `sendgrid-pp-cli engagementquality list-engagement-quality-score` — **This operation allows you to retrieve your SendGrid Engagement Quality (SEQ) scores for a specified date range**.... - `sendgrid-pp-cli engagementquality list-subuser-engagement-quality-score` — **This operation allows you to retrieve SendGrid Engagement Quality (SEQ) scores for your Subusers or customer... **geo** — Manage geo - `sendgrid-pp-cli geo` — **This endpoint allows you to retrieve your email statistics segmented by country and state/province.** **We only... **ips** — Manage ips - `sendgrid-pp-cli ips add` — **This endpoint is for adding a(n) IP Address(es) to your account.** - `sendgrid-pp-cli ips add-to-pool` — **This endpoint allows you to add an IP address to an IP pool.** You can add the same IP address to multiple pools.... - `sendgrid-pp-cli ips create-pool` — **This endpoint allows you to create an IP pool.** Before you can create an IP pool, you need to activate the IP in... - `sendgrid-pp-cli ips delete-from-pool` — **This endpoint allows you to remove an IP address from an IP pool.** - `sendgrid-pp-c