## 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

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Subscribers per page (1-100) |
| `offset` | `number` | 0 | Subscribers to skip |
| `status` | `string` | `all` | Filter by status: `all`, `active`, or `unsubscribed` |
| `query` | `string` | – | Search by email or name |

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

### Response

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "location": "New York, US",
      "source": "checkout",
      "placement": "footer",
      "unsubscribed": false,
      "unsubscribedAt": null,
      "pending": false,
      "confirmedAt": "2024-05-01T09:01:00.000Z",
      "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
  }
}
```

---

## 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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | `string` | Yes | Subscriber email address |
| `name` | `string` | No | Subscriber display name |
| `placement` | `string` | No | Storefront form or page that drove the signup, max 120 chars (e.g. `"footer"`, `"hero-banner"`) |

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

### Response (201)

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

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

| Status | Description |
|--------|-------------|
| `"queued"` | A welcome offer is configured and the discount email has been queued for delivery |
| `"pending_confirmation"` | Double opt-in is enabled; the welcome offer will fire after the subscriber confirms |
| `"off"` | No welcome offer is configured for this store |

### Already Subscribed (200)

```json
{
  "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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `subscribers` | `array` | Yes | Subscribers to import (1-1000) |
| `subscribers[].email` | `string` | Yes | Subscriber email address |
| `subscribers[].name` | `string` | No | Subscriber display name |
| `subscribers[].location` | `string` | No | Free-text location |
| `mode` | `string` | No | How to handle existing emails: `skip` (default) or `update` (refresh name/location) |

```bash
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)

```json
{
  "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

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `email` | `string` | Yes | Email to unsubscribe |

### Response

```json
{
  "status": "unsubscribed"
}
```