Sync Your Users into a Mailing List

Overview

A Shipstar mailing list is the audience for your release-notes emails. You can fill one by hand in the dashboard, but for a real product the list should mirror your own users: someone signs up and they start getting release notes; they close their account and the emails stop; they change their address and the next issue reaches the new one. The public API gives you three idempotent calls for that, and the dashboard covers the one-off import and export:

Need	Call
Add or update contacts (signup, profile change, nightly reconcile)	`PUT /email/lists/{id}/recipients`
Remove a contact (account closed, plan downgraded)	`DELETE /email/lists/{id}/recipients/{email-or-external_id}` or the batch `POST .../recipients/remove`
Check what is on the list	`GET /email/lists/{id}/recipients`, `GET /email/lists/{id}`
Initial load or backup	Import CSV / Export CSV in the dashboard (Destinations → Email → the list), or `GET .../recipients/export.csv`

All calls take an API token scoped to the project. List ids come from GET /email/lists, or create one with POST /email/lists. Management calls are free; only content generation spends credits.

The four things to know

Key by external_id. Send your own user id as external_id on every upsert. Shipstar then matches on it first, so when a user changes their email address the same recipient is updated in place instead of a second one appearing. Without it, matching falls back to the email address, which still works for simple lists. Three statuses. A recipient is active (gets emails), removed (you took them off; an upsert puts them back), or unsubscribed (they clicked the link in an email). Unsubscribed is terminal: no API call ever changes those rows, they just come back in the response as skipped_unsubscribed. Your sync does not need to track opt-outs itself. Upsert never deletes. PUT only adds and updates. Departed users have to be removed explicitly — either one at a time from your account-deletion path, or by diffing in a reconcile job (below). Retries are safe. Every call is idempotent per entry. A re-sent batch reports the repeats as unchanged / already_removed. Lists hold at most 500 active recipients; an upsert that would cross that line is rejected as a whole with a 400 so you can split it. The simplest integration: call the API from the code paths where a user is created, updated or deleted.

import os
import requests

SHIPSTAR = "https://api.shipstar.ai/api/v1"
LIST_ID = os.environ["SHIPSTAR_LIST_ID"]
HEADERS = {"Authorization": f"Bearer {os.environ['SHIPSTAR_API_TOKEN']}"}


def on_user_created_or_updated(user):
    requests.put(
        f"{SHIPSTAR}/email/lists/{LIST_ID}/recipients",
        headers=HEADERS,
        json={"recipients": [{
            "email": user.email,
            "name": user.full_name,
            "external_id": str(user.id),
            "attributes": {"plan": user.plan},
        }]},
        timeout=10,
    ).raise_for_status()


def on_user_deleted(user):
    # 404 just means they were never on the list
    requests.delete(
        f"{SHIPSTAR}/email/lists/{LIST_ID}/recipients/{user.id}",
        headers=HEADERS,
        timeout=10,
    )

const SHIPSTAR = "https://api.shipstar.ai/api/v1";
const LIST_ID = process.env.SHIPSTAR_LIST_ID!;
const headers = {
  Authorization: `Bearer ${process.env.SHIPSTAR_API_TOKEN}`,
  "Content-Type": "application/json",
};

export async function onUserCreatedOrUpdated(user: { id: string; email: string; name?: string; plan: string }) {
  await fetch(`${SHIPSTAR}/email/lists/${LIST_ID}/recipients`, {
    method: "PUT",
    headers,
    body: JSON.stringify({
      recipients: [{ email: user.email, name: user.name, external_id: user.id, attributes: { plan: user.plan } }],
    }),
  });
}

export async function onUserDeleted(userId: string) {
  await fetch(`${SHIPSTAR}/email/lists/${LIST_ID}/recipients/${encodeURIComponent(userId)}`, {
    method: "DELETE",
    headers,
  });
}

Run these after your own transaction commits, ideally from a background job so a Shipstar hiccup never fails a signup. If the call fails, retrying later is safe.

Recipe 2 — Nightly reconcile from your database

Hooks can miss events (a bulk import into your own database, a migration). A scheduled job that pushes the current truth and removes what is no longer there catches everything:

Python

import os
import requests

SHIPSTAR = "https://api.shipstar.ai/api/v1"
LIST_ID = os.environ["SHIPSTAR_LIST_ID"]
HEADERS = {"Authorization": f"Bearer {os.environ['SHIPSTAR_API_TOKEN']}"}


def chunks(items, size):
    for i in range(0, len(items), size):
        yield items[i : i + size]


def reconcile(users):
    """`users` is every account that should receive release notes."""
    wanted = {
        str(u.id): {"email": u.email, "name": u.full_name, "external_id": str(u.id)}
        for u in users
    }

    # 1. Push the current truth (adds, updates, reactivates removed ones)
    for batch in chunks(list(wanted.values()), 1000):
        r = requests.put(
            f"{SHIPSTAR}/email/lists/{LIST_ID}/recipients",
            headers=HEADERS, json={"recipients": batch}, timeout=30,
        )
        r.raise_for_status()

    # 2. Remove active recipients that are no longer in your user base
    stale, cursor = [], None
    while True:
        params = {"status": "active", "limit": 500, **({"cursor": cursor} if cursor else {})}
        page = requests.get(
            f"{SHIPSTAR}/email/lists/{LIST_ID}/recipients",
            headers=HEADERS, params=params, timeout=30,
        ).json()
        stale += [r["external_id"] for r in page["items"]
                  if r["external_id"] and r["external_id"] not in wanted]
        cursor = page["next_cursor"]
        if not cursor:
            break
    for batch in chunks(stale, 1000):
        requests.post(
            f"{SHIPSTAR}/email/lists/{LIST_ID}/recipients/remove",
            headers=HEADERS, json={"external_ids": batch}, timeout=30,
        ).raise_for_status()

Recipients without an external_id (added by hand or by an email-only import) are left alone by step 2, so a human-curated list and a synced list can coexist. Write calls are limited to 30 per minute per IP, which is 30,000 recipients a minute in 1000-entry batches — more than a list can hold. Read the RateLimit-Remaining header if you run several syncs from one host.

Recipe 3 — Zapier, n8n or Make

Use the generic HTTP / Webhook action; there is no dedicated Shipstar app and none is needed.

Trigger: new row in your CRM, new customer in Stripe, new signup in your auth provider — whatever marks someone as a user.
Action: HTTP request
- Method PUT
- URL https://api.shipstar.ai/api/v1/email/lists/<list id>/recipients
- Headers Authorization: Bearer <api token>, Content-Type: application/json
- Body (JSON):
  {"recipients": [{"email": "{{email}}", "name": "{{name}}", "external_id": "{{customer_id}}"}]}
For the churn side, a second Zap on your “customer deleted / subscription cancelled” trigger sends DELETE https://api.shipstar.ai/api/v1/email/lists/<list id>/recipients/{{customer_id}} with the same header.

Map the trigger’s stable id to external_id so a later email change updates the same recipient.

Recipe 4 — One-off CSV import or export

For an initial load from a spreadsheet, open the list in the dashboard (Destinations → Email) and use Import CSV. The importer looks for these headers, case-insensitively:

Column	Accepted headers
Email (required)	`email`, `e-mail`, `email address`
Name	`name`, `full name`, or `first name` + `last name`
External id	`external_id`, `external id`, `user_id`, `id`
Anything else	stored in `attributes` (first 20 columns)

A file with no header row and email addresses in the first column also works. You get a preview with the detected columns and counts before anything is sent, and the import runs through the same upsert as the API, so re-importing an updated file updates rather than duplicates. Export CSV on the same page (or GET .../recipients/export.csv with a token) downloads every recipient with their status — a backup you can re-import later, or feed into another tool.

Checking your work

GET /email/lists/{id} shows active_count, removed_count and unsubscribed_count; after a sync, active_count should match the number of users you pushed.
GET /email/lists/{id}/recipients?q=<email> finds one person and shows their status and the fields you wrote.
In the dashboard, the list shows the same counts, and the Sync via API button prints ready-to-paste curl commands with the list id filled in.

Upsert Recipients — full matching rules and response fields
Remove Recipients — single and batch forms
Authentication — creating and using API tokens
Error Handling — rate-limit headers and retry guidance

Get Started

Guides

Sync Your Users into a Mailing List

Overview

The four things to know

Recipe 2 — Nightly reconcile from your database

Recipe 3 — Zapier, n8n or Make

Recipe 4 — One-off CSV import or export

Checking your work

​Overview

​The four things to know

​Recipe 1 — Signup and account-deletion hooks

​Recipe 2 — Nightly reconcile from your database

​Recipe 3 — Zapier, n8n or Make

​Recipe 4 — One-off CSV import or export

​Checking your work

​Related

Overview

The four things to know

Recipe 1 — Signup and account-deletion hooks

Recipe 2 — Nightly reconcile from your database

Recipe 3 — Zapier, n8n or Make

Recipe 4 — One-off CSV import or export

Checking your work

Related