# Templates API

> Saved inbox settings. Every templates endpoint with its scope, parameters, body and an example answer.

Source: https://docs.dissolve.email/reference/templates

Base URL `https://api.dissolve.email`. Send an API key or OAuth access token as `Authorization: Bearer <token>` ([Authentication](/authentication)); an OAuth token needs the scope on each endpoint. Errors follow [one shape](/errors).

| Endpoint | Summary |
|---|---|
| `GET /v1/templates` | [List templates](#list-templates) |
| `POST /v1/templates` | [Create a template](#create-a-template) |
| `DELETE /v1/templates/{id}` | [Delete a template](#delete-a-template) |

### List templates

`GET /v1/templates` (scope `inboxes:read`)

Saved inbox settings (domain, forwarding, a webhook address) to create inboxes from, default first (Free 3, Pro 10, Business 25).

```bash cURL
curl "https://api.dissolve.email/v1/templates" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listTemplates();
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/templates", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "templates": [
    {
      "id": "tpl9Wm2QxK5rNc8Vz1LpT",
      "name": "Forwarded",
      "domain": null,
      "forwardTo": "me@example.com",
      "webhookUrl": null,
      "isDefault": true,
      "createdAt": "2026-11-19T10:00:00.000Z",
      "updatedAt": "2026-11-19T10:00:00.000Z"
    }
  ],
  "limit": 10,
  "used": 1
}
```

### Create a template

`POST /v1/templates` (scope `rules:manage`)

Saves settings to pass as `templateId` when creating an inbox. Forwarding needs Pro or Business.

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | The template's name. At most 100 characters. |
| `domain` | string or null | no | A domain from GET /v1/domains. |
| `forward_to` | string or null | no | Forward new inboxes' mail here (Pro and Business). |
| `webhook_url` | string or null | no | A webhook address kept with the template. |
| `is_default` | boolean | no | Use it when no template is named. Default `false`. |

```bash cURL
curl -X POST "https://api.dissolve.email/v1/templates" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Forwarded","forward_to":"me@example.com","is_default":true}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createTemplate({
  name: "Forwarded",
  forward_to: "me@example.com",
  is_default: true
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post("https://api.dissolve.email/v1/templates", json={
  "name": "Forwarded",
  "forward_to": "me@example.com",
  "is_default": True
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `201`

```json
{
  "id": "tpl9Wm2QxK5rNc8Vz1LpT",
  "name": "Forwarded",
  "domain": null,
  "forwardTo": "me@example.com",
  "webhookUrl": null,
  "isDefault": true,
  "createdAt": "2026-11-19T10:00:00.000Z",
  "updatedAt": "2026-11-19T10:00:00.000Z"
}
```

### Delete a template

`DELETE /v1/templates/{id}` (scope `rules:manage`)

Deletes the template. Inboxes made from it are unchanged.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The template id. |

```bash cURL
curl -X DELETE "https://api.dissolve.email/v1/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteTemplate(templateId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/templates/{template_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "success": true
}
```
