> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync your users

> Claude Code skill that mirrors your product's user base into a Shipstar mailing list from your own codebase — nightly reconcile keyed by your user id, signup and deletion hooks, the attested resubscribe call, and a signed webhook handler for unsubscribes and resubscribes.

`/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):

```
/plugin marketplace add shipstar-ai/shipstar-plugin
/plugin install shipstar@shipstar
```

Or install the skills standalone from your dashboard's Agents page
(`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](https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients.md):

1. **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.
2. **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 as
   `skipped_unsubscribed`, which the code treats as final.
3. **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.
4. **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.
5. **The way back** — when a person who unsubscribed turns the switch back
   on, the job calls [Resubscribe Recipient](https://docs.shipstar.ai/api-reference/mailing-lists/resubscribe-recipient.md)
   with a consent record, never an upsert; the switch-off path stays a
   plain remove.
6. **A signed webhook handler** — verifies `X-Shipstar-Signature`
   (HMAC-SHA256 over `<timestamp>.<raw body>`, with a replay window),
   filters on `list_id`, and mirrors `mailing_list.unsubscribed` /
   `mailing_list.resubscribed` into 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.
7. **The plan cap** — recognises the `recipient_cap_exceeded` error body,
   stops and alerts with the current count and limit instead of retrying.
8. **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)

The full skill definition is plain markdown:
[`SKILL.md`](https://app.shipstar.ai/agent-skills/sync-your-users/SKILL.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.