/shipstar:sync-your-users has your coding agent build the integration that
keeps a Shipstar mailing list equal to your own users: someone signs up and
the release emails start, closes their account and they stop, changes their
address and the next issue reaches the new one, clicks unsubscribe and
nothing in your product puts them back without their say-so. It encodes the
rules a first integration tends to learn the hard way, so the agent gets
them right the first time.
Install
Via the official Claude Code plugin (bundles the MCP connection):curl -fsSL <APP_URL>/agent-skills/install.sh | sh -s -- <APP_URL>).
When to use it
Say “sync our users into Shipstar”, “put every verified user on our release notes list”, “wire our product-updates setting to Shipstar”, or “handle Shipstar’s unsubscribe webhook”. In the dashboard, the Sync via API sheet on any mailing list has a With your agent tab with the prompt ready to paste.What the agent builds
Working in your repository, against the mailing-list API:- One list rule — a single predicate for who belongs on the list (typically active, verified, “product updates” on), used by every path below so the hooks and the reconcile never disagree. Adds the preference and its settings switch if your product has none.
- Keyed by your user id — every recipient carries your id as
external_id, so an email change updates the same person and removals can be keyed by id. Unsubscribed people come back asskipped_unsubscribed, which the code treats as final. - A nightly reconcile — pages the list’s active recipients, diffs them against the rule, erases deleted accounts and removes the rest first (so a full list still honours departures), then upserts everyone who qualifies in batches and logs the counts.
- Hooks off the request path — verification, the preference switch and account deletion enqueue a job that pushes that one user’s current state; a Shipstar outage never slows or fails the user’s own action.
- The way back — when a person who unsubscribed turns the switch back on, the job calls Resubscribe Recipient with a consent record, never an upsert; the switch-off path stays a plain remove.
- A signed webhook handler — verifies
X-Shipstar-Signature(HMAC-SHA256 over<timestamp>.<raw body>, with a replay window), filters onlist_id, and mirrorsmailing_list.unsubscribed/mailing_list.resubscribedinto your preference so your UI shows the truth and the reconcile agrees with it. Answers 2xx fast and never 4xxs an event it cannot match. - The plan cap — recognises the
recipient_cap_exceedederror body, stops and alerts with the current count and limit instead of retrying. - Verification — no-ops without config, a hand-run reconcile whose counts match the list, an off/on switch round-trip that goes through resubscribe, the dashboard’s Send test against the handler, a real unsubscribe → resubscribe round-trip, and an erase on account deletion.
Requirements
- A Shipstar API token (Dashboard → API Tokens) and a mailing list id (Destinations → Email)
- A webhook endpoint registered under Destinations → Webhooks with both mailing-list events ticked, and its signing secret in your config
- A backend with a job queue or scheduler for the hooks and the nightly run (any stack; the skill speaks plain HTTP)
SKILL.md.