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

# List Email References

> Gallery emails from brands like yours, or the whole gallery, to model a new email on

List real emails from the [Sequenzy email gallery](https://sequenzy.com/email-examples) to model a new email on, for the kind of email you are creating. By default they come from the gallery brands most like you: Sequenzy compares your company description with every brand's emails by meaning, ranking each brand by its best-matching emails. Nothing is stored: a change to your description counts on the next request, and new gallery brands within 10 minutes. With `scope=all`, list the whole gallery for that kind of email instead. These are the examples in the **Gallery** tab of the dashboard's new campaign, transactional and sequence pickers, with its **Brands like yours** and **All examples** switch.

Each email's `url` works with [Create Template from Example](/api-reference/templates/create-from-example), and each sequence's with [Create Sequence from Example](/api-reference/sequences/create-from-example).

Requires the `templates:read` scope.

## Request

<ParamField query="kind" type="string" required>
  `campaign` (promotions, newsletters and product updates), `sequence`
  (lifecycle emails, plus whole sequences) or `transactional`.
</ParamField>

<ParamField query="scope" type="string" default="similar">
  `similar`: emails (and, for `kind=sequence`, whole sequences) from the 12
  gallery brands most like you, closest first. `all`: the whole gallery for the
  `kind`, newest first, 48 per page.
</ParamField>

<ParamField query="q" type="string">
  Search words, up to 80 characters, matched by meaning, most relevant first.
  With `scope=similar` only those brands' emails are searched. A search is paged
  like `scope=all`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page for `scope=all` or a search, from 1 to 200.
</ParamField>

<ParamField query="subtype" type="string">
  For `scope=similar` without `q`: a gallery subtype to list first, such as
  `password_reset` or `welcome`. Ignored when it does not belong to the `kind`.
</ParamField>

<ParamField query="limit" type="integer" default="24">
  For `scope=similar` without `q`: most emails to return, from 1 to 60. Also
  caps how many sequences are returned.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always `true` on success.
</ResponseField>

<ResponseField name="kind" type="string">
  The requested `kind`.
</ResponseField>

<ResponseField name="scope" type="string">
  `similar` or `all`.
</ResponseField>

<ResponseField name="page" type="integer">
  This page. `scope=similar` without a search is always one page.
</ResponseField>

<ResponseField name="pageCount" type="integer">
  How many pages there are, at most 200.
</ResponseField>

<ResponseField name="profile" type="string">
  `ready`, or `missing` when your company has neither a description nor company
  context to compare with gallery brands yet. `scope=similar` is then empty; add
  a description in your dashboard settings, or use `scope=all`. Always `ready`
  for `scope=all`, which does not use it.
</ResponseField>

<ResponseField name="brands" type="object[]">
  With `scope=similar`, the gallery brands most like you, closest first: `name`,
  `domain`, `slug` and their gallery `url`. Your own brand is never included.
  Empty for `scope=all`.
</ResponseField>

<ResponseField name="emails" type="object[]">
  Gallery emails. With `scope=similar` and no search: the asked-for subtype
  first, then one email per brand in turn, closest brands first.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Gallery email ID.</ResponseField>
    <ResponseField name="subject" type="string | null">Subject line.</ResponseField>
    <ResponseField name="preheader" type="string | null">Preview text.</ResponseField>
    <ResponseField name="type" type="string | null">Email type, such as `transactional`.</ResponseField>
    <ResponseField name="subtype" type="string | null">Email subtype, such as `password_reset`.</ResponseField>
    <ResponseField name="sentAt" type="string">When the brand sent it (ISO 8601).</ResponseField>
    <ResponseField name="brand" type="object">The sender: `name`, `domain` and `slug`.</ResponseField>
    <ResponseField name="url" type="string">Gallery page for the email, or for an email in a sequence its sequence page ending in `#email-{slug}`. Either is accepted by Create Template from Example.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sequences" type="object[]">
  For `kind=sequence` on the first page only: whole gallery sequences with `id`,
  `name`, `emailCount`, `brand` and `url`. With `scope=similar`, closest brands
  first; with a search, the sequences of the best matches. Empty otherwise.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "kind": "transactional",
    "scope": "similar",
    "page": 1,
    "pageCount": 1,
    "profile": "ready",
    "brands": [
      {
        "name": "Linear",
        "domain": "linear.app",
        "slug": "linear",
        "url": "https://sequenzy.com/email-examples/brands/linear"
      }
    ],
    "emails": [
      {
        "id": "g_4kq9Lw",
        "subject": "Reset your Linear password",
        "preheader": null,
        "type": "transactional",
        "subtype": "password_reset",
        "sentAt": "2026-09-14T10:02:00.000Z",
        "brand": { "name": "Linear", "domain": "linear.app", "slug": "linear" },
        "url": "https://sequenzy.com/email-examples/brands/linear/emails/reset-your-linear-password"
      }
    ],
    "sequences": []
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "API key is missing required scope: templates:read"
  }
  ```

  ```json 503 theme={null}
  {
    "error": "Similar brands are unavailable right now. Try again shortly.",
    "code": "REFERENCES_UNAVAILABLE"
  }
  ```
</ResponseExample>

The lists are empty when the email gallery is not available, or with `scope=similar` when your company has no description yet (`profile` is `missing`). With `scope=similar` and no `q`, every result is on page 1, so later pages are empty. A 503 with code `REFERENCES_UNAVAILABLE` means your description could not be compared with gallery brands right now; nothing changed, so retry shortly or use `scope=all`. A 422 means a parameter failed validation, such as an unknown `kind` or `scope`, or a `limit` over 60.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.