`lumail@2.1.0` · [`lumail.subscribers`](/docs/sdk/v2/subscribers)

```typescript
subscribers.listEvents(idOrEmail: string, params?: ListEventsParams): Promise<LumailResult<ListEventsResponse>>
```

Events recorded on one contact. The SDK forwards `limit`, `after`, `before`, and `eventTypes` (JSON-stringified). `order`, `startDate`, `endDate`, and `search` are typed on `ListEventsParams` but are not forwarded.

## Path Parameters

| Name | Type | Description |
| ----------- | ------ | ------------------------------------- |
| `idOrEmail` | string | **Required.** Subscriber id or email. |

## Query Parameters

| Name | Type | Description |
| ------------ | ----------------------- | ------------------------------------------------- |
| `limit` | number | Page size. Forwarded. |
| `after` | string | Cursor: older events. Forwarded. |
| `before` | string | Cursor: newer events. Forwarded by the SDK. |
| `eventTypes` | `SubscriberEventType[]` | Filter by event type. Forwarded as a JSON string. |
| `order` | `"asc"` or `"desc"` | Typed only. Not forwarded by the SDK. |
| `startDate` | string | Typed only. Not forwarded by the SDK. |
| `endDate` | string | Typed only. Not forwarded by the SDK. |
| `search` | string | Typed only. Not forwarded by the SDK. |

## Response Fields

| Field | Type | Description |
| ---------- | ------------------- | --------------------------------------------------------------------------------------- |
| `object` | `"list"` | Discriminator. Always `list`. |
| `has_more` | boolean | `true` when another page exists. |
| `data` | `SubscriberEvent[]` | Events. Each row: `id`, `eventType`, `data`, `subscriberId`, `createdAt`, `subscriber`. |

`data` is `{ object, data, has_more }`. Failures return `{ data: null, error: { name, message, statusCode } }`.


## API Reference
**Method:** GET
**Endpoint:** /api/v2/subscribers/:subscriber/events

### SDK
```ts
import { Lumail } from "lumail";

const lumail = new Lumail({ apiKey: process.env.LUMAIL_API_KEY });
const { data, error } = await lumail.subscribers.listEvents(
  "user@example.com",
  { limit: 20, eventTypes: ["EMAIL_OPENED", "EMAIL_CLICKED"] },
);
if (error) {
  throw error;
}
for (const event of data.data) {
  console.log(event.eventType, event.createdAt);
}
```

### cURL
```bash
curl "https://lumail.io/api/v2/subscribers/user@example.com/events?limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### JavaScript
```javascript
const response = await fetch(
  "https://lumail.io/api/v2/subscribers/user@example.com/events?limit=20",
  {
    headers: {
      Authorization: "Bearer YOUR_API_TOKEN",
    },
  },
);
const data = await response.json();
```

### Success Response
```json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "evt_abc123",
      "eventType": "EMAIL_OPENED",
      "data": null,
      "subscriberId": "sub_abc123",
      "createdAt": "2026-09-05T10:30:00.000Z",
      "subscriber": {
        "id": "sub_abc123",
        "email": "user@example.com",
        "name": "Ada"
      }
    }
  ]
}
```

### Error Response
```json
{
  "name": "not_found",
  "message": "Subscriber not found",
  "statusCode": 404
}
```