Mail Templates endpoints (Admin API)

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

Last synced from FeatherPanel 15b94e9 on 23 Oct 2026.

On this page

Defined in backend/app/routes/admin/mail-templates.php. Authentication used here: Admin. Read Authentication for how to send credentials and 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: AdminPermission: admin.email.templates.viewRoute name: admin-mail-templatesController: MailTemplatesController::indexroute source

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

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: AdminPermission: admin.email.templates.viewRoute name: admin-mail-templates-showController: MailTemplatesController::showroute source

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

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: AdminPermission: admin.email.templates.createRoute name: admin-mail-templates-createController: MailTemplatesController::createroute source

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 (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

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

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: AdminPermission: admin.email.templates.editRoute name: admin-mail-templates-updateController: MailTemplatesController::updateroute source

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 (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

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

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: AdminPermission: admin.email.templates.deleteRoute name: admin-mail-templates-deleteController: MailTemplatesController::deleteroute source

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

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

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: AdminPermission: admin.email.templates.editRoute name: admin-mail-templates-restoreController: MailTemplatesController::restoreroute source

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

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: AdminPermission: admin.email.templates.deleteRoute name: admin-mail-templates-hard-deleteController: MailTemplatesController::hardDeleteroute source

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

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: AdminPermission: admin.email.templates.createRoute name: admin-mail-templates-mass-emailController: MailTemplatesController::sendMassEmailroute source

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 (application/json) · Response data: 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

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: AdminPermission: admin.email.templates.createRoute name: admin-mail-templates-test-emailController: MailTemplatesController::sendTestEmailroute source

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

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

Mail Templates endpoints (Admin API)

Endpoints

GET/api/admin/mail-templates

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

POST/api/admin/mail-templates

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

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

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

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

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

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