`GET https://lumail.io/api/v1/subscribers`

List subscribers in your organization with optional filtering by tag, status, or search query. Results are sorted by creation date (most recent first).

## Query Parameters

| Parameter | Type   | Default        | Description                                                                                                                   |
| --------- | ------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `tag`     | string | —              | Filter by tag name (case-insensitive). Only returns subscribers who have this tag.                                            |
| `status`  | string | `"SUBSCRIBED"` | Filter by subscriber status. One of: `SUBSCRIBED`, `UNSUBSCRIBED`, `PENDING_CONFIRMATION`, `BOUNCED`, `BANNED`, `COMPLAINED`. |
| `limit`   | number | `50`           | Maximum number of subscribers to return (1–100).                                                                              |
| `query`   | string | —              | Search by name or email (case-insensitive partial match).                                                                     |

## Response

- **Success (200 OK)** — Returns a list of subscribers matching the filters.
- **Error (401 Unauthorized)** — Invalid or missing API token.
- **Error (429 Too Many Requests)** — Rate limit exceeded.

## Response Fields

| Field                       | Type           | Description                                         |
| --------------------------- | -------------- | --------------------------------------------------- |
| `success`                   | boolean        | Indicates if the operation was successful           |
| `subscribers`               | array          | Array of subscriber objects                         |
| `subscribers[].id`          | string         | Unique identifier for the subscriber                |
| `subscribers[].email`       | string         | Email address of the subscriber                     |
| `subscribers[].name`        | string or null | Name of the subscriber (if provided)                |
| `subscribers[].status`      | string         | Current status of the subscriber                    |
| `subscribers[].createdAt`   | string         | ISO 8601 timestamp of when the subscriber was added |
| `subscribers[].tags`        | array          | Array of tag objects associated with the subscriber |
| `subscribers[].tags[].id`   | string         | Unique identifier for the tag                       |
| `subscribers[].tags[].name` | string         | Name of the tag                                     |
| `total`                     | number         | Total number of subscribers matching the filters    |
| `limit`                     | number         | The limit used in the query                         |

## Usage Examples

Use this endpoint to:

- Fetch subscribers by tag for integrations (e.g., display recent signups from a specific campaign)
- Search for subscribers by name or email
- List subscribers with a specific status for reporting
- Power dashboards or external tools that need subscriber data


## API Reference
**Method:** GET
**Endpoint:** /api/v1/subscribers

## Request Examples
### SDK (TypeScript)
```ts
import { Lumail } from "lumail";
const lumail = new Lumail({ apiKey: "YOUR_API_TOKEN" });

// List all subscribers
const { subscribers, total } = await lumail.subscribers.list();

// Filter by tag, status, and search
const result = await lumail.subscribers.list({
  tag: "newsletter",
  status: "SUBSCRIBED",
  limit: 10,
  query: "john",
});
console.log(result.subscribers);
```

### cURL
```bash
# List all subscribed subscribers
curl -X GET "https://lumail.io/api/v1/subscribers" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Filter by tag
curl -X GET "https://lumail.io/api/v1/subscribers?tag=aiblueprint-dev&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Filter by status and search
curl -X GET "https://lumail.io/api/v1/subscribers?status=SUBSCRIBED&query=john&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### JavaScript
```javascript
const response = await fetch(
  'https://lumail.io/api/v1/subscribers?tag=newsletter&limit=10&status=SUBSCRIBED',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
    },
  }
);

const data = await response.json();
console.log(data.subscribers);
```

### Python
```python
import requests

url = "https://lumail.io/api/v1/subscribers"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN"
}
params = {
    "tag": "newsletter",
    "limit": 10,
    "status": "SUBSCRIBED"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)
```

## Response Examples
### Success Response
```json
{
  "success": true,
  "subscribers": [
    {
      "id": "sub_TTYPR5tWDh",
      "email": "john@example.com",
      "name": "John Doe",
      "status": "SUBSCRIBED",
      "createdAt": "2026-04-02T10:30:00.000Z",
      "tags": [
        { "id": "tag_JqaddtEx7z", "name": "newsletter" }
      ]
    },
    {
      "id": "sub_Abc123xyz",
      "email": "jane@example.com",
      "name": null,
      "status": "SUBSCRIBED",
      "createdAt": "2026-04-01T08:15:00.000Z",
      "tags": [
        { "id": "tag_JqaddtEx7z", "name": "newsletter" },
        { "id": "tag_rdEPhyjnfA", "name": "vip" }
      ]
    }
  ],
  "total": 142,
  "limit": 10
}
```

### Error Response
```json
{
  "message": "Missing or invalid Authorization header"
}
```