# Template API - Read

Use the read endpoints to retrieve email templates for your account. You can list all templates with filtering and sorting, retrieve a single template by ID, or fetch a template's full HTML content.

---

## Endpoints

| Method | URL | Description |
|---|---|---|
| GET | `https://e1.envoke.com/v2/templates` | Return a list of templates. |
| GET | `https://e1.envoke.com/v2/templates/{ID}` | Return a single template. |

Authentication is via HTTP Basic Auth using your API ID and API Key.

---

## List Templates

```
GET https://e1.envoke.com/v2/templates
```

Returns a JSON array of templates for your account, sorted by most recently modified first. Supports filtering, sorting, pagination, and field selection.

### Query Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `limit` | integer | `10` | Maximum number of results to return. Hard cap is `100` unless `?fields=` or `?result_type=kvp` is also set (see note below). |
| `skip` | integer | `0` | Number of records to skip. Use with `limit` to paginate. |
| `fields` | string | *(all)* | Comma-separated list of fields to include in each result. See limit note below. |
| `result_type` | string | *(array)* | Set to `kvp` to receive results as a key-value object (`{ "id": "name" }`). See limit note below. |
| `filter[name]` | string | — | Filter by template name. |
| `filter[status]` | string | — | Filter by status: `published` or `unpublished`. |
| `filter[language]` | string | — | Filter by language. Accepts a two-letter IETF code (`en`, `fr`). |
| `filter[group]` | string | — | Filter by group name. |
| `filter[id]` | integer | — | Filter by template ID. |
| `sort[name]` | string | — | Sort by template name. Value: `asc` or `desc`. |
| `sort[modified_time]` | string | — | Sort by last modified date. Value: `asc` or `desc`. |
| `sort[create_time]` | string | — | Sort by creation date. Value: `asc` or `desc`. |
| `sort[language]` | string | — | Sort by language. Value: `asc` or `desc`. |
| `sort[group]` | string | — | Sort by group name. Value: `asc` or `desc`. |
| `sort[status]` | string | — | Sort by status. Value: `asc` or `desc`. |

**Note — limit behaviour with `?fields=` and `?result_type=kvp`:** When either of these parameters is present, the default limit increases to 10,000 (returning all records if no explicit limit is specified) and a `?limit=` value above 100 is honoured as-is. This allows full exports and dropdown population without pagination.

### Filter Operators

All `filter[field]` parameters support the following operators:

| Operator | Example | Description |
|---|---|---|
| *(none)* | `?filter[status]=published` | Exact match |
| `(ne)` | `?filter[status][(ne)]=published` | Not equal |

*Note: The `(regex)` operator is not supported. Use exact match or `(ne)` instead.*

*Note: URL-encode brackets in production requests (e.g. `%5B` for `[`).*

### Response

A JSON array of template objects. Returns an empty array (`[]`) if no templates exist or no results match the filter.

```json
[
  {
    "id": "1",
    "external_id": "a1b2c3d4e5f6",
    "preview_url": "https://engage.envoke.com/m/acme-corp/m/a1b2c3d4e5f6",
    "name": "Welcome Email",
    "status": "published",
    "language": "en",
    "group": "Onboarding",
    "create_time": "2026-04-01 09:00:00",
    "modified_time": "2026-04-10 14:00:00"
  }
]
```

`html` is never included in list responses.

---

## Get a Single Template

```
GET https://e1.envoke.com/v2/templates/{ID}
```

Returns a single template object. Replace `{ID}` with the Envoke template ID.

Add `?include_html=1` to include the full HTML content of the template in the response.

If the ID is not found, the API returns an empty array (`[]`).

### Response (default)

```json
{
  "id": "42",
  "external_id": "a1b2c3d4e5f6",
  "preview_url": "https://engage.envoke.com/m/acme-corp/m/a1b2c3d4e5f6",
  "name": "Welcome Email",
  "status": "published",
  "language": "en",
  "group": "",
  "create_time": "2026-04-11 09:00:00",
  "modified_time": "2026-04-11 09:00:00"
}
```

### Response with `?include_html=1`

```json
{
  "id": "42",
  "external_id": "a1b2c3d4e5f6",
  "preview_url": "https://engage.envoke.com/m/acme-corp/m/a1b2c3d4e5f6",
  "name": "Welcome Email",
  "status": "published",
  "language": "en",
  "group": "",
  "create_time": "2026-04-11 09:00:00",
  "modified_time": "2026-04-11 09:00:00",
  "html": "<html><body><h1>Welcome!</h1></body></html>"
}
```

---

## Examples

### Return all templates (default pagination)

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates"
```

### Paginate through results

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?limit=10&skip=10"
```

### Filter by status

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?filter%5Bstatus%5D=published"
```

### Filter by group

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?filter%5Bgroup%5D=Onboarding"
```

### Filter by language

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?filter%5Blanguage%5D=fr"
```

### Filter excluding a group

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?filter%5Bgroup%5D%5B%28ne%29%5D=Archived"
```

### Sort by name ascending

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?sort%5Bname%5D=asc"
```

### Sort by most recently created

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?sort%5Bcreate_time%5D=desc"
```

### Return only specific fields

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?fields=id,name,status"
```

### Return as a key-value map (for dropdowns)

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates?result_type=kvp"
```

Response:

```json
{ "1": "Welcome Email", "2": "Monthly Newsletter" }
```

### Get a single template by ID

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates/42"
```

### Get a single template with its HTML

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "https://e1.envoke.com/v2/templates/42?include_html=1"
```

---

*Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.*

*Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).*