Subscribers API

REST API endpoints for newsletter subscriber management.

List Subscribers

GET /api/v1/subscribers

Returns a paginated subscriber list with per-subscriber purchase stats (orderCount, totalSpent, lastOrderAt) for audience segmentation. The sensitive unsubscribe token is never returned.

Query Parameters

curl \
  -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/subscribers?status=active&limit=20"

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "location": "New York, US",
      "source": "checkout",
      "placement": "footer",
      "locale": "en-US",
      "unsubscribed": false,
      "unsubscribedAt": null,
      "pending": false,
      "confirmedAt": "2024-05-01T09:01:00.000Z",
      "suppressedAt": null,
      "suppressedReason": null,
      "suppressedDetail": null,
      "orderCount": 3,
      "totalSpent": 12500,
      "lastOrderAt": "2024-06-10T14:22:00.000Z",
      "createdAt": "2024-05-01T09:00:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}

Paused Addresses

An address is paused when mail can no longer reach it: it hard-bounced, or the person reported a campaign as spam. Campaigns and back-in-stock notifications skip a paused address until a merchant reactivates it from the dashboard. This is separate from unsubscribed, which is the person's own choice.

Pass status=bounced to list only paused addresses:

curl \
  -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/subscribers?status=bounced"

Create Subscriber

POST /api/v1/subscribers

Adds an email address to the store's subscriber list. If the email is already subscribed, returns a 200 with { status: "already_subscribed" } instead of creating a duplicate.

When double opt-in is enabled in your store's newsletter settings (settings.newsletter.doubleOptIn), new subscribers are created with pending: true and receive a confirmation email. The welcome offer is only triggered after the subscriber confirms. If the email already exists and is still pending, the confirmation email is re-sent (at most once per day).

Request Body

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "name": "Jane Doe", "placement": "footer", "locale": "en-US"}' \
  https://your-store.yns.store/api/v1/subscribers

Response (201)

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "placement": "footer",
  "locale": "en-US",
  "pending": false,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "welcomeOffer": { "status": "queued" }
}

The welcomeOffer.status field indicates whether a welcome email was triggered for this subscriber:

Already Subscribed (200)

{
  "status": "already_subscribed"
}

Import Subscribers

POST /api/v1/subscribers/import

Bulk-adds subscribers – the programmatic equivalent of the dashboard CSV import. Up to 1000 subscribers per request. The mode field controls handling of emails that already exist.

Request Body

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribers": [
      {"email": "jane@example.com", "name": "Jane Doe", "location": "New York, US"},
      {"email": "john@example.com", "name": "John Smith"}
    ],
    "mode": "skip"
  }' \
  https://your-store.yns.store/api/v1/subscribers/import

Response (200)

{
  "imported": 2,
  "skipped": 0,
  "updated": 0
}

A 403 is returned with { error, limit, count } when the subscriber limit for your plan is reached.

Delete Subscriber

DELETE /api/v1/subscribers?email=jane@example.com

Unsubscribes an email address.

Query Parameters

Response

{
  "status": "unsubscribed"
}