# Subscribers

Source: https://pushary.com/docs/web-push/server-sdk/subscribers
Last updated: 2026-05-11

> Manage push notification subscribers with the server SDK

## Overview [#overview]

Subscribers are users who have opted in to receive push notifications from your site. The server SDK provides methods to list, view, update, and delete subscribers.

## List Subscribers [#list-subscribers]

```typescript
const { data, hasMore, nextCursor } = await pushary.subscribers.list({
  limit: 100,
  status: 'active',
})

for (const subscriber of data) {
  console.log(subscriber.id, subscriber.browser, subscriber.country)
}
```

### Parameters [#parameters]

| Parameter    | Type       | Description                          |
| ------------ | ---------- | ------------------------------------ |
| `limit`      | `number`   | Max results (default: 100, max: 500) |
| `cursor`     | `string`   | Pagination cursor                    |
| `status`     | `string`   | Filter by status                     |
| `externalId` | `string`   | Filter by external ID                |
| `tags`       | `string[]` | Filter by tags                       |

### Response [#response]

```typescript
interface PaginatedResponse<Subscriber> {
  data: Subscriber[]
  hasMore: boolean
  nextCursor?: string
}
```

## Get Subscriber [#get-subscriber]

```typescript
const subscriber = await pushary.subscribers.get('sub_123')

console.log(subscriber.browser)    // 'Chrome'
console.log(subscriber.country)    // 'US'
console.log(subscriber.tags)       // ['vip', 'newsletter']
```

### Subscriber Object [#subscriber-object]

```typescript
interface Subscriber {
  id: string
  siteId: string
  endpoint: string
  status: 'active' | 'unsubscribed' | 'expired' | 'bounced'
  browser?: string
  os?: string
  deviceType?: string
  country?: string
  city?: string
  timezone?: string
  language?: string
  tags?: string[]
  externalId?: string
  createdAt: string
  lastActiveAt?: string
}
```

## Update Subscriber [#update-subscriber]

Update tags or external ID:

```typescript
const updated = await pushary.subscribers.update('sub_123', {
  tags: ['vip', 'newsletter'],
  externalId: 'user-456',
})
```

### Update Fields [#update-fields]

| Field        | Type       | Description                      |
| ------------ | ---------- | -------------------------------- |
| `tags`       | `string[]` | Subscriber tags for segmentation |
| `externalId` | `string`   | Your internal user ID            |
| `customData` | `object`   | Custom metadata                  |

## Delete Subscriber [#delete-subscriber]

Permanently remove a subscriber:

```typescript
await pushary.subscribers.delete('sub_123')
```

## Count Subscribers [#count-subscribers]

Get subscriber statistics:

```typescript
const count = await pushary.subscribers.count()

console.log(count.total)         // 1500
console.log(count.active)        // 1200
console.log(count.unsubscribed)  // 300
```

## Pagination [#pagination]

Handle large subscriber lists with cursor pagination:

```typescript
const fetchAllSubscribers = async () => {
  const allSubscribers: Subscriber[] = []
  let cursor: string | undefined

  do {
    const { data, hasMore, nextCursor } = await pushary.subscribers.list({
      limit: 500,
      cursor,
    })
    
    allSubscribers.push(...data)
    cursor = hasMore ? nextCursor : undefined
  } while (cursor)

  return allSubscribers
}
```

## Filtering by Tags [#filtering-by-tags]

Target specific segments:

```typescript
const vipSubscribers = await pushary.subscribers.list({
  tags: ['vip'],
  status: 'active',
})
```

## Using External IDs [#using-external-ids]

Link subscribers to your users:

```typescript
await pushary.subscribers.update('sub_123', {
  externalId: 'user-456',
})

const userSubscribers = await pushary.subscribers.list({
  externalId: 'user-456',
})
```