> For the complete documentation index, see [llms.txt](https://teamleader-sdk.mcore-services.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://teamleader-sdk.mcore-services.dev/api-reference/templates/mail-templates.md).

# Mail Templates

Manage mail templates in Teamleader Focus.

```php
Teamleader::mailTemplates()
```

|                          |                                                                 |
| ------------------------ | --------------------------------------------------------------- |
| Class                    | `McoreServices\TeamleaderSDK\Resources\Templates\MailTemplates` |
| Create / update / delete | — / — / —                                                       |
| Pagination               | No                                                              |

## Endpoints

* `mailTemplates.list`

## Filters

Passed as the first argument to `list()`. Any other key throws.

| Filter          | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `department_id` | Filter by department UUID (optional)                                    |
| `type`          | Template type (REQUIRED): invoice, quotation, work\_order, credit\_note |

## Accepted values

Public constants on the class. Body fields and enum values outside these lists throw before the request is sent.

| Constant | Values                                              |
| -------- | --------------------------------------------------- |
| `TYPES`  | `invoice`, `quotation`, `work_order`, `credit_note` |

## Methods

### `list()`

```php
list(array $filters = [], array $options = []): array
```

List mail templates with filtering

Note: The 'type' parameter is REQUIRED by the API

* `$filters` — Filters to apply (type is required)
* `$options` — Additional options (not used for this endpoint)

**Throws** `InvalidArgumentException` When required type parameter is missing or invalid

### `forType()`

```php
forType(string $type, ?string $departmentId = null): array
```

Get mail templates for a specific type

* `$type` — Template type (invoice, quotation, work\_order, credit\_note)
* `$departmentId` — Optional department UUID

**Throws** `InvalidArgumentException`

### `forInvoices()`

```php
forInvoices(?string $departmentId = null): array
```

Get mail templates for invoices

* `$departmentId` — Optional department UUID

### `forQuotations()`

```php
forQuotations(?string $departmentId = null): array
```

Get mail templates for quotations

* `$departmentId` — Optional department UUID

### `forWorkOrders()`

```php
forWorkOrders(?string $departmentId = null): array
```

Get mail templates for work orders

* `$departmentId` — Optional department UUID

### `forCreditNotes()`

```php
forCreditNotes(?string $departmentId = null): array
```

Get mail templates for credit notes

* `$departmentId` — Optional department UUID

### `findByName()`

```php
findByName(string $name, string $type, ?string $departmentId = null): ?array
```

Find a mail template by name

* `$name` — Template name to search for
* `$type` — Template type (required)
* `$departmentId` — Optional department UUID

**Throws** `InvalidArgumentException`

### `findByLanguage()`

```php
findByLanguage(string $language, string $type, ?string $departmentId = null): ?array
```

Find a mail template by language

* `$language` — Language code (e.g., 'en', 'nl', 'fr')
* `$type` — Template type (required)
* `$departmentId` — Optional department UUID

**Throws** `InvalidArgumentException`

### `asOptions()`

```php
asOptions(string $type, ?string $departmentId = null, string $labelField = 'name'): array
```

Get all mail templates as key-value pairs for dropdown options

* `$type` — Template type (required)
* `$departmentId` — Optional department UUID
* `$labelField` — Field to use as label (default: 'name')

**Throws** `InvalidArgumentException`

### `groupedByLanguage()`

```php
groupedByLanguage(string $type, ?string $departmentId = null): array
```

Get template names grouped by language

* `$type` — Template type (required)
* `$departmentId` — Optional department UUID

**Throws** `InvalidArgumentException`

### `getResponseStructure()`

```php
getResponseStructure(): array
```

Get response structure documentation

## Examples

Get all mail templates for invoices:

```php
$templates = Teamleader::mailTemplates()->forType('invoice');
```

Get mail templates for quotations in a specific department:

```php
$templates = Teamleader::mailTemplates()->forType('quotation', 'department-uuid');
```

Find a mail template by name:

```php
$template = Teamleader::mailTemplates()->findByName('Send link in english', 'invoice');
```

Get mail templates as key-value pairs for dropdowns:

```php
$options = Teamleader::mailTemplates()->asOptions('invoice');
```