# Mail Templates endpoints (Admin API)

> 9 FeatherPanel Admin API endpoints from admin/mail-templates.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/admin/mail-templates/

Defined in [`backend/app/routes/admin/mail-templates.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php). Authentication used here: **Admin**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### GET `/api/admin/mail-templates`

- Auth: Admin
- Permission: `admin.email.templates.view`
- Route name: `admin-mail-templates`
- Controller: [`MailTemplatesController::index`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L27)

**Get all mail templates** Retrieve a paginated list of all mail templates with optional search functionality and soft-deleted template inclusion.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number for pagination |
| `limit` | query | integer | no | Number of records per page |
| `search` | query | string | no | Search term to filter templates by name or subject |
| `include_deleted` | query | boolean | no | Include soft-deleted templates in results |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `templates` | MailTemplate\[\] |  |
| `pagination` | MailTemplatePagination |  |
| `search` | object |  |

```bash
curl -X GET "$PANEL_URL/api/admin/mail-templates" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Mail templates retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/mail-templates/{id}`

- Auth: Admin
- Permission: `admin.email.templates.view`
- Route name: `admin-mail-templates-show`
- Controller: [`MailTemplatesController::show`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L39)

**Get mail template by ID** Retrieve a specific mail template by its ID.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Mail template ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `template` | MailTemplate |  |

```bash
curl -X GET "$PANEL_URL/api/admin/mail-templates/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Mail template retrieved successfully · `400` Bad request - Invalid template ID · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Mail template not found

### POST `/api/admin/mail-templates`

- Auth: Admin
- Permission: `admin.email.templates.create`
- Route name: `admin-mail-templates-create`
- Controller: [`MailTemplatesController::create`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L56)

**Create new mail template** Create a new mail template with name, subject, and body. Validates field lengths and ensures template name uniqueness.

Request body: [`MailTemplateCreate`](https://featherpanel.com/docs/api/schemas/#schema-mailtemplatecreate) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Template name |
| `subject` | string | yes | Email subject |
| `body` | string | yes | Email body content |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `template_id` | integer | ID of the created template |

```bash
curl -X POST "$PANEL_URL/api/admin/mail-templates" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","subject":"","body":""}'
```

Plugin events: [`featherpanel:admin:mail_templates:template:created`](https://featherpanel.com/docs/plugins/events/mail-templates/#mail-template-created)

Responses: `201` Mail template created successfully · `400` Bad request - Missing required fields, invalid data types, or validation errors · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `409` Conflict - Template name already exists · `500` Internal server error - Failed to create template

### PATCH `/api/admin/mail-templates/{id}`

- Auth: Admin
- Permission: `admin.email.templates.edit`
- Route name: `admin-mail-templates-update`
- Controller: [`MailTemplatesController::update`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L68)

**Update mail template** Update an existing mail template. Only provided fields will be updated. Validates field lengths and ensures template name uniqueness.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Mail template ID |

Request body: [`MailTemplateUpdate`](https://featherpanel.com/docs/api/schemas/#schema-mailtemplateupdate) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Template name |
| `subject` | string | no | Email subject |
| `body` | string | no | Email body content |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X PATCH "$PANEL_URL/api/admin/mail-templates/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","subject":"","body":""}'
```

Plugin events: [`featherpanel:admin:mail_templates:template:updated`](https://featherpanel.com/docs/plugins/events/mail-templates/#mail-template-updated)

Responses: `200` Mail template updated successfully · `400` Bad request - No data provided, invalid data types, or validation errors · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Mail template not found · `409` Conflict - Template name already exists · `500` Internal server error - Failed to update template

### DELETE `/api/admin/mail-templates/{id}`

- Auth: Admin
- Permission: `admin.email.templates.delete`
- Route name: `admin-mail-templates-delete`
- Controller: [`MailTemplatesController::delete`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L85)

**Soft delete mail template** Soft delete a mail template (marks as deleted but preserves data). System templates (ID 1-10) cannot be deleted.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Mail template ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X DELETE "$PANEL_URL/api/admin/mail-templates/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:admin:mail_templates:template:deleted`](https://featherpanel.com/docs/plugins/events/mail-templates/#mail-template-deleted)

Responses: `200` Mail template deleted successfully · `400` Bad request - Invalid template ID or system template deletion attempted · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Mail template not found · `500` Internal server error - Failed to delete template

### POST `/api/admin/mail-templates/{id}/restore`

- Auth: Admin
- Permission: `admin.email.templates.edit`
- Route name: `admin-mail-templates-restore`
- Controller: [`MailTemplatesController::restore`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L102)

**Restore soft deleted mail template** Restore a soft-deleted mail template by marking it as active again.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Mail template ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/admin/mail-templates/$ID/restore" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Mail template restored successfully · `400` Bad request - Invalid template ID · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Mail template not found · `500` Internal server error - Failed to restore template

### DELETE `/api/admin/mail-templates/{id}/hard-delete`

- Auth: Admin
- Permission: `admin.email.templates.delete`
- Route name: `admin-mail-templates-hard-delete`
- Controller: [`MailTemplatesController::hardDelete`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L119)

**Permanently delete mail template** Permanently delete a mail template from the database. This action cannot be undone.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Mail template ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X DELETE "$PANEL_URL/api/admin/mail-templates/$ID/hard-delete" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Mail template permanently deleted successfully · `400` Bad request - Invalid template ID · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Mail template not found · `500` Internal server error - Failed to permanently delete template

### POST `/api/admin/mail-templates/mass-email`

- Auth: Admin
- Permission: `admin.email.templates.create`
- Route name: `admin-mail-templates-mass-email`
- Controller: [`MailTemplatesController::sendMassEmail`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L136)

**Send mass email to all users** Send a mass email to all active users with valid email addresses. Emails are queued for delivery and processed by the mail sender cron job.

Request body: [`MassEmail`](https://featherpanel.com/docs/api/schemas/#schema-massemail) (application/json) · Response data: [`MassEmailResult`](https://featherpanel.com/docs/api/schemas/#schema-massemailresult)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `subject` | string | yes | Email subject |
| `body` | string | yes | Email body content |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `queued_count` | integer | Number of emails successfully queued |
| `failed_count` | integer | Number of emails that failed to queue |
| `total_users` | integer | Total number of valid users found |

```bash
curl -X POST "$PANEL_URL/api/admin/mail-templates/mass-email" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"subject":"","body":""}'
```

Responses: `200` Mass email queued successfully · `400` Bad request - Missing required fields, invalid data types, validation errors, or no valid users found · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `500` Internal server error - Failed to queue mass email

### POST `/api/admin/mail-templates/test-email`

- Auth: Admin
- Permission: `admin.email.templates.create`
- Route name: `admin-mail-templates-test-email`
- Controller: [`MailTemplatesController::sendTestEmail`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/MailTemplatesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/mail-templates.php#L148)

**Send test email** Send a test email to a specified email address to verify mail configuration and template rendering.

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | Recipient email address |
| `subject` | string | yes | Email subject |
| `body` | string | yes | Email body content |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |
| `queue_id` | integer | Mail queue ID |

```bash
curl -X POST "$PANEL_URL/api/admin/mail-templates/test-email" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"","subject":"","body":""}'
```

Responses: `200` Test email queued successfully · `400` Bad request - Missing required fields, invalid email format, or validation errors · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `500` Internal server error - Failed to queue test email