# List templates

> Find templates by name, status, origin, or category.

`GET https://api-connect.nxiom.com/api/v1/emails/templates`

## Authorization

Requires `email.full_access`.

## Query parameters

| Field | Type | Description |
| --- | --- | --- |
| `page` | integer · optional | Page number, starting at 1; defaults to 1. |
| `limit` | integer · optional | 1–100; defaults to 50. |
| `status` | string · optional | `draft`, `published`, `changes_in_draft`, or `archived`. See [Templates](/docs/learn/templates#drafts-and-published-versions). |
| `search` | string · optional | Matches the name, alias, or description. |
| `origin` | string · optional | `custom` or `prebuilt`. |
| `category` | string · optional | Exact category. |

## Request

### cURL

```shell
curl "https://api-connect.nxiom.com/api/v1/emails/templates?status=published&limit=50" \
  -H "Authorization: Bearer $NEXIOM_API_KEY"
```

### Node.js

```typescript
import { NexiomConnect } from '@nexiom/connect';

const apiKey = process.env.NEXIOM_API_KEY;
if (!apiKey) throw new Error('Set NEXIOM_API_KEY');

const nexiom = new NexiomConnect({ apiKey });

const { data, error } = await nexiom.templates.list({ status: 'published', limit: 50 });

if (error) throw new Error(`${error.code}: ${error.message}`);
for (const template of data.items) {
  console.log(template.id, template.name);
}
```

### PHP

```php
<?php

use Nexiom\Connect\NexiomConnect;

$apiKey = getenv('NEXIOM_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set NEXIOM_API_KEY');
}

$nexiom = new NexiomConnect($apiKey);

$page = $nexiom->templates->list(['status' => 'published', 'limit' => 50]);

foreach ($page['items'] as $template) {
    echo $template['id'], ' ', $template['name'], PHP_EOL;
}
```

## Response

HTTP `200`. Templates are ordered by most recently updated. Each item has the same fields as [Retrieve a template](/docs/api/templates/retrieve). Use `total`, `page`, and `limit` to request further pages.

### 200 OK

Example successful response.

```json
{
  "message": "Email templates fetched",
  "data": {
    "items": [
      {
        "id": "template_example",
        "organization_id": "organization_example",
        "project_id": "project_example",
        "name": "Welcome",
        "alias": "welcome",
        "description": null,
        "category": null,
        "origin": "custom",
        "locale": "en",
        "draft_version_id": null,
        "published_version_id": "version_example",
        "archived_at": null,
        "usage_count": 12,
        "last_used_at": "2026-10-03T09:00:00.000Z",
        "created_at": "2026-09-20T09:00:00.000Z",
        "updated_at": "2026-09-21T09:00:00.000Z",
        "draft_version": null,
        "published_version": {
          "id": "version_example",
          "template_id": "template_example",
          "version_number": 2,
          "status": "published",
          "subject": "Welcome, {{first_name}}",
          "preview_text": null,
          "from_name": null,
          "from_address": null,
          "reply_to": null,
          "content": {},
          "html": "<p>Hi {{first_name}}</p>",
          "text": "Hi {{first_name}}",
          "thumbnail_url": null,
          "editor_revision": 4,
          "created_by_customer_id": null,
          "published_by_customer_id": null,
          "published_at": "2026-09-21T09:00:00.000Z",
          "created_at": "2026-09-21T08:00:00.000Z",
          "updated_at": "2026-09-21T09:00:00.000Z",
          "variables": [
            {
              "id": "variable_example",
              "key": "first_name",
              "type": "string",
              "required": true,
              "fallback_value": null
            }
          ]
        }
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}
```

### 400 Bad Request

The request is invalid. Correct it before retrying; `details` lists the failing fields.

```json
{
  "error": "invalid_argument",
  "message": "Request doesn't match the schema",
  "correlationId": "req_example",
  "details": {
    "context": "body",
    "issues": []
  }
}
```

### 401 Unauthorized

The API key is missing, malformed, revoked, or expired.

```json
{
  "error": "unauthorized",
  "message": "Invalid API key",
  "correlationId": "req_example"
}
```

### 403 Forbidden

The API key lacks a required permission, or its domain restriction does not allow this sender.

```json
{
  "error": "not_allowed",
  "message": "Missing required API key permissions: email.full_access",
  "correlationId": "req_example"
}
```

---

Source: https://connect.nxiom.com/docs/api/templates/list