---
title: "Get emails"
method: GET
path: "/v1/emails"
tags: ["Emails"]
---

# Get emails

`GET /v1/emails`

Unified email-design read. Omit `emailId` to LIST the brand’s designs (newest first) under `{ data, pagination }` — each row carries `emailId`, the latest `emailVersionId`, `title`, `status`, `previewImage` (when captured), and `updatedAt`. Filter with `?status=` and the `createdAtFrom/To` + `updatedAtFrom/To` ISO-8601 windows; paginate with `limit` + `cursor`. Pass `?emailId=` to fetch ONE design — returns `{ data: [row] }` (no `pagination`), `404 EMAIL_NOT_FOUND` on an unknown / cross-brand id. Add detail-only `?include=html` (rendered HTML) and/or `?include=versions` (lean `{ version, emailVersionId }` history) — both rejected without `emailId`.

## Query parameters

- `emailId` string
- `include` string
- `status` 'streaming' | 'complete' | 'error'
- `createdAtFrom` string, date-time
- `createdAtTo` string, date-time
- `updatedAtFrom` string, date-time
- `updatedAtTo` string, date-time
- `limit` union
  - number
  - string
- `cursor` string

## Response `200`

A page of email designs (list mode), or `{ data: [row] }` (detail mode).

- EmailsListResponse
  - `data` object[], required
    - `emailId` string, required
    - `emailVersionId` string
    - `title` string, required
    - `status` 'streaming' | 'complete' | 'error', required
    - `previewImage` string, uri
    - `updatedAt` string, date-time, required
    - `previewText` string — The design's inbox preview line, read directly from the latest version's JSX <Preview> (its single source of truth) — what a send delivers when no explicit `previewText` override is passed to POST /v1/sends. Detail-only; absent when the design has no <Preview>.
    - `html` string
    - `versions` object[]
      - `version` union, required
        - integer
        - 'latest'
      - `emailVersionId` string, required
  - `pagination` object
    - `limit` integer, required
    - `cursor` string, nullable, required
    - `hasMore` boolean, required

## Other responses

- `400` — Invalid query (unknown param, bad enum, `*From` later than its `*To`, or `include` without `emailId`).
- `401` — The API key was missing, invalid, or revoked.
- `403` — The caller does not have the required `emails` permission.
- `404` — Email design not found in the API-key brand. Cross-brand ids intentionally surface as 404 (never 403) so the API does not leak cross-brand existence.
- `429` — The request hit the rolling rate limit window.
- `500` — Unexpected internal error.

---

[API](https://skmtc.net/brew/apis/brew-public-api-v1.md) · [All operations](https://skmtc.net/brew/apis/brew-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/brew/brew-public-api-v1/versions/db96cfedc6c5/schema)