> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drin.run/llms.txt
> Use this file to discover all available pages before exploring further.

# List emails

> GET /v1/emails — page through messages, filtered by status, direction, or search.

Page through your messages, newest first. Filter by delivery status, direction (inbound or outbound), or a free-text search over sender, recipient, and subject.

**`GET /v1/emails`**

Returns a [cursor page](/api-reference/pagination) of message summaries. Combine the filters below with `limit` and `cursor`; keep the filters constant across a walk.

## Query parameters

<ParamField query="status" type="string">
  Filter by message status — e.g. `delivered`, `bounced`, `queued`, `complained`.
</ParamField>

<ParamField query="direction" type="string">
  `inbound` or `outbound`.
</ParamField>

<ParamField query="q" type="string">
  Search recipient, sender, or subject.
</ParamField>

<ParamField query="limit" type="integer">
  Page size, `1`–`100`.
</ParamField>

<ParamField query="cursor" type="string">
  The `nextCursor` from the previous response.
</ParamField>

## Headers

<ParamField header="X-Drin-Product" type="header">
  Scopes the listing to one project for account-wide keys (alias: `X-Drin-Sender`).
</ParamField>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.drin.run/v1/emails?status=bounced&limit=50" \
    -H "Authorization: Bearer $DRIN_API_KEY"
  ```

  ```typescript Node.js theme={null}
  import { DrinClient } from "@drin00/sdk";

  const drin = new DrinClient({ apiKey: process.env.DRIN_API_KEY });

  // One page
  const page = await drin.emails.list({ status: "bounced", limit: 50 });

  // Or walk every page
  for await (const message of drin.emails.paginate({ direction: "inbound" })) {
    console.log(message.from, message.subject);
  }
  ```
</CodeGroup>

## Response

`200 OK` — a page of message summaries plus a `nextCursor`. Each summary omits the body and event lifecycle; fetch those with [`GET /v1/emails/{id}`](/api-reference/emails/get).

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "msg_01HZX9K3T2QF7P0M4N8B6C5D",
      "from": "onboarding@yourdomain.com",
      "to": ["you@example.com"],
      "subject": "Hello from Drin",
      "status": "delivered",
      "direction": "outbound",
      "createdAt": "2026-06-02T17:04:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6Im1zZ18wMUhaVyJ9"
}
```

<Note>
  **Reaching the end.** When `nextCursor` is `null`, there are no more results. See [Pagination](/api-reference/pagination) for the full walk and the SDK's auto-paginating iterator.
</Note>