# List a lead's emails

Source: https://help.ruuster.com/api/leads-emails

```http
GET https://api.ruuster.com/v1/leads/{leadId}/emails
```

Ruuster emails sent to one lead (saved-search alerts and listing updates), newest first, with delivery, opens and clicks.

- Authentication: `x-api-key` and `x-email` headers of an owner or admin
- Rate limit: *lookup* call, 20 per minute per key, within the 120 per minute

## Path parameters

| Name | Type | Description |
|---|---|---|
| `leadId` | string | `user:<uuid>` or `unregistered:<uuid>`, exactly as returned in `leadId` |

## Query parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `from` | date | 30 days before `to` | First day, `YYYY-MM-DD`, included |
| `to` | date | today | Day after the last day, `YYYY-MM-DD`, excluded |
| `cursor` | string | | `meta.nextCursor` from the previous page. Omit for the first page |
| `limit` | integer | `100` | Rows per page, 1 to 500 |

## Response

Each item in `data.emails`: `emailId` (`em_…`, opaque), `sentAt`, `subject`, `savedSearchName`, `delivered`, `deliveredAt`, `opens`, `humanOpen`, `firstOpenAt`, `clicks`, `firstClickAt`.

An email with `opens` above 0 and `humanOpen: false` was most likely opened only by an automated scanner. Opens and clicks for roughly the last two weeks can still increase.

## Example request

cURL:

```bash
curl -s "https://api.ruuster.com/v1/leads/user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04/emails?from=2026-09-28&to=2026-10-01&limit=3" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL"
```

Node.js:

```javascript
const res = await fetch("https://api.ruuster.com/v1/leads/user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04/emails?from=2026-09-28&to=2026-10-01&limit=3", {
  headers: {
    "x-api-key": process.env.RUUSTER_API_KEY,
    "x-email": process.env.RUUSTER_EMAIL,
  },
});
const body = await res.json();
if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.requestId})`);
console.log(body.data);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.ruuster.com/v1/leads/user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04/emails?from=2026-09-28&to=2026-10-01&limit=3",
    headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"]},
    timeout=30,
)
body = res.json()
if not body["ok"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} ({body.get("requestId")})')
print(body["data"])
```

## Example response

```json
{
  "ok": true,
  "data": {
    "emails": [
      { "emailId": "em_9Km1vR3tZ6aB", "sentAt": "2026-09-30T12:00:28Z", "subject": "New and Updated Property Listings!",
        "savedSearchName": "Catalina Foothills 3bd", "delivered": true, "deliveredAt": "2026-09-30T12:00:31Z",
        "opens": 0, "humanOpen": false, "firstOpenAt": null, "clicks": 0, "firstClickAt": null },
      { "emailId": "em_4Hn8sD2qY1eL", "sentAt": "2026-09-30T00:00:12Z", "subject": "Price drop on a home you saved",
        "savedSearchName": null, "delivered": true, "deliveredAt": "2026-09-30T00:00:15Z",
        "opens": 2, "humanOpen": false, "firstOpenAt": "2026-09-30T00:00:19Z", "clicks": 0, "firstClickAt": null },
      { "emailId": "em_7Yq2pX8mT4cW", "sentAt": "2026-09-29T12:00:31Z", "subject": "3 new homes match \"Catalina Foothills 3bd\"",
        "savedSearchName": "Catalina Foothills 3bd", "delivered": true, "deliveredAt": "2026-09-29T12:00:34Z",
        "opens": 1, "humanOpen": true, "firstOpenAt": "2026-09-29T14:12:02Z", "clicks": 1, "firstClickAt": "2026-09-29T14:15:40Z" }
    ]
  },
  "meta": { "range": { "from": "2026-09-28", "to": "2026-10-01", "tz": "America/Chicago" }, "total": 5, "nextCursor": "cur_Wm1x9cPq7Lm3XvT8wR" }
}
```