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

# List Emails

> Retrieve a paginated list of all emails sent through your account.

### Headers

<ParamField header="Content-Type" type="string">
  `application/json`
</ParamField>

### Query Parameters

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="number" default="10">
  Number of emails to return per page.
</ParamField>

<ParamField query="search" type="string">
  Search query to filter emails by subject, recipient, or sender.
</ParamField>

<ParamField query="start_date" type="string">
  Filter emails created on or after this date (ISO 8601 format, e.g., `2025-11-01T00:00:00Z`).
</ParamField>

<ParamField query="end_date" type="string">
  Filter emails created on or before this date (ISO 8601 format, e.g., `2025-11-30T23:59:59Z`).
</ParamField>

<ParamField query="statuses" type="string">
  Filter by email status. Can be a single status or comma-separated list. Possible values: `processing`, `queued`, `delivered`, `failed`, `bounced`, `complaint`.
</ParamField>

<ParamField query="api_key_id" type="number">
  Filter emails sent using a specific API key ID.
</ParamField>

### Response

<ResponseField name="status" type="number">
  HTTP status code. Returns `200` when emails are retrieved successfully.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable message describing the result of the operation.
</ResponseField>

<ResponseField name="data" type="object">
  Contains the paginated list of emails and pagination metadata.

  <Expandable title="properties">
    <ResponseField name="data" type="array">
      Array of email objects. HTML and full metadata are not included in list view.

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Unique identifier for the email.
        </ResponseField>

        <ResponseField name="message_id" type="string">
          The message ID used in email headers.
        </ResponseField>

        <ResponseField name="from_address" type="string">
          The sender email address.
        </ResponseField>

        <ResponseField name="to_addresses" type="array">
          Array of recipient email addresses.
        </ResponseField>

        <ResponseField name="subject" type="string">
          The email subject line.
        </ResponseField>

        <ResponseField name="size" type="number">
          Total size of the email in bytes.
        </ResponseField>

        <ResponseField name="inline" type="number">
          Number of inline attachments.
        </ResponseField>

        <ResponseField name="attachments" type="number">
          Number of file attachments.
        </ResponseField>

        <ResponseField name="api_key_id" type="number">
          ID of the API key used to send the email.
        </ResponseField>

        <ResponseField name="snippet" type="string">
          Text preview/snippet of the email content.
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO 8601 timestamp when the email was created.
        </ResponseField>

        <ResponseField name="team_id" type="string">
          The team ID that owns this email.
        </ResponseField>

        <ResponseField name="metadata" type="object">
          Basic email metadata. HTML and text content are empty in list view.

          <Expandable title="properties">
            <ResponseField name="from" type="string">
              Sender email address.
            </ResponseField>

            <ResponseField name="to" type="array">
              Array of recipient email addresses.
            </ResponseField>

            <ResponseField name="cc" type="array | null">
              CC recipients, if any.
            </ResponseField>

            <ResponseField name="bcc" type="array | null">
              BCC recipients, if any.
            </ResponseField>

            <ResponseField name="reply_to" type="string | null">
              Reply-to email address, if set.
            </ResponseField>

            <ResponseField name="text" type="string">
              Empty in list view. Use GET by ID to retrieve full content.
            </ResponseField>

            <ResponseField name="html" type="string">
              Empty in list view. Use GET by ID to retrieve full content.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="opened_at" type="string | null">
          ISO 8601 timestamp when the email was first opened. Null if not opened.
        </ResponseField>

        <ResponseField name="delivered_at" type="string | null">
          ISO 8601 timestamp when the email was delivered. Null if not yet delivered.
        </ResponseField>

        <ResponseField name="click_count" type="number">
          Number of times links in the email were clicked.
        </ResponseField>

        <ResponseField name="status" type="string">
          Current email status. Possible values: `processing`, `queued`, `delivered`, `failed`, `bounced`, `complaint`.
        </ResponseField>

        <ResponseField name="credits_used" type="number">
          Number of credits consumed to send this email.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Pagination metadata.

      <Expandable title="properties">
        <ResponseField name="page" type="number">
          Current page number.
        </ResponseField>

        <ResponseField name="total_records" type="number">
          Total number of emails across all pages.
        </ResponseField>

        <ResponseField name="total_pages" type="number">
          Total number of pages available.
        </ResponseField>

        <ResponseField name="limit" type="number">
          Number of records per page.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
      "status": 200,
      "message": "emails retrieved successfully.",
      "data": {
          "data": [
              {
                  "id": "xxxxx",
                  "message_id": "xxxxx@me.thepurplebox.io",
                  "from_address": "hello@yourdomain.com",
                  "to_addresses": [
                      "user@example.com"
                  ],
                  "subject": "Complete Your Sign-In to thePurpleBox",
                  "size": 8915,
                  "inline": 0,
                  "attachments": 0,
                  "api_key_id": 2,
                  "snippet": "Complete Your Sign-In Hey user@example.com, We noticed a sign-in attempt to your purplebox account...",
                  "created_at": "2025-11-21T10:51:55.330945Z",
                  "team_id": "xxxxx",
                  "metadata": {
                      "from": "hello@yourdomain.com",
                      "to": [
                          "user@example.com"
                      ],
                      "cc": null,
                      "bcc": null,
                      "reply_to": null,
                      "text": "",
                      "html": ""
                  },
                  "opened_at": null,
                  "delivered_at": null,
                  "click_count": 0,
                  "status": "processing",
                  "credits_used": 1
              }
          ],
          "pagination": {
              "page": 1,
              "total_records": 11,
              "total_pages": 2,
              "limit": 10
          }
      }
  }
  ```
</ResponseExample>