# List template versions

> Read the saved and published versions of a template, newest first.

`GET https://api-connect.nxiom.com/api/v1/emails/templates/{templateId}/versions`

## Authorization

Requires `email.full_access`.

## Path parameters

| Field | Type | Description |
| --- | --- | --- |
| `templateId` | string · required | The template ID. |

## Query parameters

| Field | Type | Description |
| --- | --- | --- |
| `limit` | integer · optional | Versions per response, from `1` to `100`; default `50`. |
| `beforeVersion` | integer · optional | Return only versions numbered below this one. Pass the last `version_number` of the previous response to read older versions. |

Versions are returned newest first. Continue with `beforeVersion` until a response has fewer than `limit` versions.

## Request

### cURL

```shell
curl "https://api-connect.nxiom.com/api/v1/emails/templates/YOUR_TEMPLATE_ID/versions?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.versions('YOUR_TEMPLATE_ID', { limit: 50 });

if (error) throw new Error(`${error.code}: ${error.message}`);
for (const version of data) {
  console.log(version.version_number, version.status);
}
```

### 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);

$versions = $nexiom->templates->versions('YOUR_TEMPLATE_ID', ['limit' => 50]);

foreach ($versions as $version) {
    echo $version['version_number'], ' ', $version['status'], PHP_EOL;
}
```

## Response

HTTP `200`. Each version has the same fields as `published_version` in [Retrieve a template](/docs/api/templates/retrieve). `status` is `draft` for the version being edited, `published` for the version sends use, and `saved` for earlier versions.

### 200 OK

Example successful response.

```json
{
  "message": "Email template versions fetched",
  "data": [
    {
      "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
        }
      ]
    }
  ]
}
```

### 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"
}
```

### 404 Not Found

No resource with this ID exists in the API key’s project.

```json
{
  "error": "not_found",
  "code": "resource_not_found",
  "message": "Resource not found",
  "correlationId": "req_example"
}
```

---

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