Email API
The email module sends ClientFence’s email from templates, keeps the outgoing queue and, when Log Sent Emails to Database is on, a history of sent email that clients also see. These calls read the history and queue, send email, and manage the templates. See Email settings and history and Email templates.
Admin calls need Module access on the Email card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”email_get_list
Section titled “email_get_list”POST /api/admin/email/email_get_list
Lists the sent email history, newest first.
Permission: View email history (email.view_email_history)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer | Only emails of this client. |
search |
string | Text in the subject, sender, recipients or body. |
sender |
string | Part of the sender address. |
recipient |
string | Part of the recipient address. |
subject |
string | Part of the subject. |
date_from |
string | First day to include, such as 2026-11-01. |
date_to |
string | Last day to include. |
id |
integer | Only the email with this ID. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has id, client_id, sender, recipients, subject, content_html (cleaned of scripts), content_text, has_attachment, created_at and updated_at.
Emails are kept here only while Log Sent Emails to Database is on. Emails with a sign-in link (password resets, sign-in PINs) are never kept.
Example
Request parameters:
{ "client_id": 12, "per_page": 1}result:
{ "pages": 14, "page": 1, "per_page": 1, "total": 14, "list": [ { "id": 77, "client_id": 12, "sender": "billing@example.com", "recipients": "jane@example.com", "subject": "Invoice #2026-0042 is ready", "content_html": "<p>Hello Jane, …</p>", "content_text": null, "has_attachment": true, "created_at": "2026-11-17 06:00:12", "updated_at": "2026-11-17 06:00:12" } ]}email_get
Section titled “email_get”POST /api/admin/email/email_get
Returns one email of the sent email history.
Permission: View email history (email.view_email_history)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The email’s ID. |
Returns: An object with the fields of an email_get_list row.
Errors:
- Email ID was not passed
- Email not found
POST /api/admin/email/send
Sends an email you write. It is queued and sent right after the response (or by cron).
Permission: Send emails (email.send_emails)
| Parameter | Type | Description |
|---|---|---|
to |
string, required | Recipient address. |
to_name |
string, required | Recipient name. |
from |
string, required | Sender address. |
from_name |
string, required | Sender name. |
subject |
string, required | The subject. |
content |
string, required | The HTML body. |
client_id |
integer | A client, so the email shows in the client’s email history. |
Returns: true once the email is queued.
Errors:
- Receiver email is required (and the other missing-parameter messages)
Example
Request parameters:
{ "to": "jane@example.com", "to_name": "Jane Doe", "from": "support@example.com", "from_name": "Example Hosting", "subject": "Your new server", "content": "<p>Hello Jane, your server is ready.</p>", "client_id": 12}result:
trueemail_resend
Section titled “email_resend”POST /api/admin/email/email_resend
Sends an email from the history again, to the same recipients, with its attachment.
Permission: Send emails (email.send_emails)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The email’s ID. |
Returns: true once it is queued again; false while the demo module is active.
Errors:
- Email ID was not passed
- Email not found
email_delete
Section titled “email_delete”POST /api/admin/email/email_delete
Deletes an email from the sent email history.
Permission: Delete email history (email.delete_email_history)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The email’s ID. |
Returns: true
Errors:
- Email ID was not passed
- Email not found
template_get_list
Section titled “template_get_list”POST /api/admin/email/template_get_list
Lists the email templates, by category and code.
Permission: View email templates (email.view_templates)
| Parameter | Type | Description |
|---|---|---|
search |
string | Text in the code, subject, content, category or description. |
code |
string | Part of the template code, such as invoice. |
category |
string | Part of the category, such as staff. |
enabled |
boolean | Only turned-on (true) or turned-off (false) templates. |
type |
string | custom for templates you added; any other value for the built-in ones. |
id |
integer | Only the template with this ID. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has id, action_code, category, enabled, subject (the raw template text), title (a readable name made from the subject), description, is_custom, has_default (a built-in template with a default to reset to), is_overridden (a built-in template you changed), has_error and last_error.
Example
Request parameters:
{ "code": "invoice_paid", "per_page": 1}result:
{ "pages": 1, "page": 1, "per_page": 1, "total": 1, "list": [ { "id": 21, "action_code": "mod_invoice_paid", "category": "invoice", "enabled": true, "subject": "[{{ guest.system_company.name }}] {{ 'Payment received'|trans }}", "title": "Payment received", "description": "Sent when an invoice is paid.", "is_custom": false, "has_default": true, "is_overridden": false, "has_error": false, "last_error": null } ]}template_get
Section titled “template_get”POST /api/admin/email/template_get
Returns one email template with its content, preview variables and language versions.
Permission: View email templates (email.view_templates)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The template’s ID. |
Returns: An object: id, action_code, category, enabled, subject and content (the text in use: your change, or the built-in default), description, is_custom, has_default, is_overridden, vars (the variables of the last email sent with it, used for previews, with secrets masked), subject_override and content_override (your saved texts; null for a custom template), has_error, last_error, translations (language code => subject, content) and default_locale.
Errors:
- Email ID was not passed
- Email template not found
template_delete
Section titled “template_delete”POST /api/admin/email/template_delete
Deletes a custom email template with its language versions and staff group links. Built-in templates cannot be deleted.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The template’s ID. |
Returns: true
Errors:
- Email template not found
- Only custom email templates can be deleted
template_create
Section titled “template_create”POST /api/admin/email/template_create
Adds a custom email template, for your own code to send with template_send.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
action_code |
string, required | The code you send it by, such as custom_welcome_pack. |
subject |
string, required | The subject, a Twig template. |
content |
string, required | The body, a Twig template (Markdown and HTML are allowed). |
enabled |
boolean | Whether it is sent. Default false. |
category |
string | A category to group it under. |
Returns: The new template’s ID.
Errors:
- Email template code is required / Email template subject is required / Email template content is required
- Only a Super Administrator can change this email: it carries a sign-in link or code. (code 403) for the emails with a sign-in link or code: password resets (client, account user, staff), the sign-up and confirmation emails, the account user invitation and the sign-in PIN emails (client and staff).
- A Twig error when the subject or content does not render.
- Email template rendering error: Variable “
” does not exist … (code 9999) when a text uses a variable that only your template_sendcall gives, without a default.
The subject and content are checked by rendering them with example values of c (the client) and staff, so {{ c.first_name }} works. A variable that only your own template_send call gives, such as order, needs a default for the check: {{ order.id|default('') }}. When the email is sent, the variables have their values.
Example
Request parameters:
{ "action_code": "custom_welcome_pack", "subject": "Welcome to {{ guest.system_company.name }}", "content": "Hello {{ c.first_name }}, …", "enabled": true, "category": "custom"}result:
64template_update
Section titled “template_update”POST /api/admin/email/template_update
Changes an email template. Only the fields you send change; the texts are checked by rendering them first.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The template’s ID. |
enabled |
boolean | Turn sending on or off. |
category |
string | A new category. |
subject |
string | A new subject. |
content |
string | A new body. |
translations |
object | The language versions: language code => subject and content. It replaces all versions: a language left out loses its version. Leave the parameter out to keep them. |
Returns: true
Errors:
- Email template not found
- Invalid locale code:
- Enter a subject and a message for every language version.
- A Twig error when a text does not render.
- Only a Super Administrator can change this email: it carries a sign-in link or code. (code 403) for the emails with a sign-in link or code: password resets (client, account user, staff), the sign-up and confirmation emails, the account user invitation and the sign-in PIN emails (client and staff).
- Email template rendering error: Variable “
” does not exist … (code 9999) for a custom template whose text uses a variable that only your template_sendcall gives, without a default (see template_create).
Changing a sign-in email (see the errors) needs a Super Administrator; resetting it and switching it on or off need only this permission. A built-in template whose texts match the default again is no longer marked as changed. The template’s saved error is cleared.
Example
Request parameters:
{ "id": 21, "enabled": true, "translations": { "de_DE": { "subject": "Zahlung erhalten", "content": "Hallo {{ c.first_name }}, …" } }}result:
truetemplate_localize
Section titled “template_localize”POST /api/admin/email/template_localize
Writes a template text out in another language, as the start of a language version: each {{ 'Text'|trans }} becomes the translated text. Nothing is saved.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
lang |
string, required | A turned-on language, such as de_DE. |
subject |
string | The subject to write out. |
content |
string | The body to write out. |
Returns: An object: subject and content.
Errors:
- Invalid locale code:
template_group_get_list
Section titled “template_group_get_list”POST /api/admin/email/template_group_get_list
Lists the staff groups a staff email template goes to.
Permission: View email templates (email.view_templates)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The template’s ID. |
Returns: A list of groups, each with id, name and protected.
Errors:
- Email template not found
template_group_add
Section titled “template_group_add”POST /api/admin/email/template_group_add
Sends a staff email template to the members of one more staff group.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The template’s ID. |
group_id |
integer, required | The staff group’s ID. |
Returns: true (also when the group was already linked).
Errors:
- Staff group ID was not passed
- Email template not found
- Staff group not found
template_group_remove
Section titled “template_group_remove”POST /api/admin/email/template_group_remove
Stops sending a staff email template to a staff group.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The template’s ID. |
group_id |
integer, required | The staff group’s ID. |
Returns: true (also when the group was not linked).
Errors:
- Staff group ID was not passed
- Email template not found
template_reset
Section titled “template_reset”POST /api/admin/email/template_reset
Puts a built-in email template back to its default subject and body.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | The template code, such as mod_invoice_paid. |
Returns: true
Errors:
- Email template code was not passed
- Email template
does not have a file-backed default - Custom email template
cannot be reset to a default
template_render
Section titled “template_render”POST /api/admin/email/template_render
Renders a template text for a preview, with the template’s preview variables.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The template’s ID. |
_tpl |
string | The text to render. Default: the template’s body. |
lang |
string | A turned-on language to render in. |
Returns: The rendered text (HTML entities decoded).
Errors:
- Email template not found
- A Twig error when the text does not render.
batch_template_generate
Section titled “batch_template_generate”POST /api/admin/email/batch_template_generate
Resets every built-in email template to its default subject and body. Your custom templates stay.
Permission: Manage email templates (email.manage_templates)
No parameters.
Returns: true
This cannot be undone: every change you made to a built-in template is lost (language versions stay).
batch_template_disable
Section titled “batch_template_disable”POST /api/admin/email/batch_template_disable
Turns off every email template, after adding any missing built-in templates of active modules.
Permission: Manage email templates (email.manage_templates)
No parameters.
Returns: true
No email is sent until you turn templates on again, including invoices and password resets.
batch_template_enable
Section titled “batch_template_enable”POST /api/admin/email/batch_template_enable
Turns on every email template, after adding any missing built-in templates of active modules.
Permission: Manage email templates (email.manage_templates)
No parameters.
Returns: true
template_validate_all
Section titled “template_validate_all”POST /api/admin/email/template_validate_all
Renders every email template and its language versions with their preview variables, and saves the error of each one that fails.
Permission: Manage email templates (email.manage_templates)
No parameters.
Returns: An object: valid and invalid (counts) and errors (each with id, action_code and error; a language version’s error starts with its language code).
Example
Request parameters:
{}result:
{ "valid": 118, "invalid": 1, "errors": [ { "id": 64, "action_code": "custom_welcome_pack", "error": "Unexpected \"}\" in \"__string_template__\" at line 1." } ]}send_test
Section titled “send_test”POST /api/admin/email/send_test
Sends the test email to the signed-in staff member’s own address at once, to check the sending settings.
Permission: Send emails (email.send_emails)
No parameters.
Returns: true when it was sent; false when the test template is turned off.
Errors:
- The sending error, such as a failed SMTP connection, is returned as the error.
batch_sendmail
Section titled “batch_sendmail”POST /api/admin/email/batch_sendmail
Sends the queued emails now, as cron does: up to the per-run limit, for at most the time limit of the email settings.
Permission: Send emails (email.send_emails)
No parameters.
Returns: null when the queue was processed; false while the demo module is active.
An email that fails stays queued and is tried again on the next run; after the set number of tries and at least 3 days it is dropped.
template_send
Section titled “template_send”POST /api/admin/email/template_send
Sends an email from a template, with the variables you give.
Permission: Send emails (email.send_emails)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | The template code, such as custom_welcome_pack. A code with no template creates a turned-off custom one from default_subject and default_template. |
to_client |
integer | A client ID: the email goes to the client’s email (or billing email, see client_billing_email), in the client’s language, and the template gets the client as c. Cannot be combined with to. |
to |
string | A recipient address, with to_name. |
to_name |
string | The recipient’s name. |
to_staff |
boolean | true: send to the active staff in the template’s staff groups. |
from |
string | Sender address. Default: the email settings’ sender, else the company email. |
from_name |
string | Sender name. |
send_now |
boolean | true: send at once instead of after the response. |
default_subject |
string | Subject for a template that does not exist yet. |
default_template |
string | Body for a template that does not exist yet. |
default_description |
string | Description for a template that does not exist yet. |
(variables) |
mixed | Every other key is a template variable, such as order or invoice. |
Returns: true when the email was queued or sent; false when the template is turned off, or when no template has the code (a turned-off custom template with that code is then made).
Errors:
- Template code not passed
- Receiver is not defined. Define to or to_client or to_staff parameter
- client_billing_email cannot be set via the API
- Parameters
toandto_clientcannot be combined. Client-bound emails are always sent to the client’s registered email address. - The “from” email address cannot be empty
- Client not found
A client email also goes to the client’s contacts who get that kind of email, and shows in the client’s email history while logging is on.
Example
Request parameters:
{ "code": "custom_welcome_pack", "to_client": 12}result:
truebatch_template_delete
Section titled “batch_template_delete”POST /api/admin/email/batch_template_delete
Deletes several custom email templates with their language versions and staff group links. Built-in templates in the list are skipped.
Permission: Manage email templates (email.manage_templates)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Template IDs. |
Returns: true
Errors:
- IDs were not passed
- Email template not found (nothing is deleted when one ID is unknown)
batch_delete
Section titled “batch_delete”POST /api/admin/email/batch_delete
Deletes several emails from the sent email history.
Permission: Delete email history (email.delete_email_history)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Email IDs. |
Returns: true
Errors:
- IDs were not passed
- Email not found (the emails before the unknown ID are already deleted)
get_queue
Section titled “get_queue”POST /api/admin/email/get_queue
Lists the outgoing email queue, highest priority first.
Permission: View email history (email.view_email_history)
| Parameter | Type | Description |
|---|---|---|
status |
string | pending, sending, unsent or failed. |
client_id |
integer | Only emails of this client. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has id, recipient, subject, content, to_name, status, tries, has_attachment, created_at and updated_at.
Client calls
Section titled “Client calls”get_list (client)
Section titled “get_list (client)”POST /api/client/email/get_list
Lists the emails sent to the signed-in client, newest first.
| Parameter | Type | Description |
|---|---|---|
search |
string | Text in the subject, sender, recipients or body. |
subject |
string | Part of the subject. |
date_from |
string | First day to include. |
date_to |
string | Last day to include. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list with the fields of the admin email_get_list rows.
Emails are kept only while Log Sent Emails to Database is on. An authorized user needs the View emails sent to the account permission.
get (client)
Section titled “get (client)”POST /api/client/email/get
Returns one email sent to the signed-in client.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The email’s ID. |
Returns: An object: id, client_id, sender, recipients, subject, content_html, content_text, has_attachment, created_at and updated_at.
Errors:
- Email ID was not passed
- Email not found (code 404), also for another client’s email
An authorized user needs the View emails sent to the account permission.
resend (client)
Section titled “resend (client)”POST /api/client/email/resend
Sends one of the client’s emails again, to the same recipients.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The email’s ID. |
Returns: true once it is queued again.
Errors:
- Email not found (code 404)
- Too many attempts: 5 resends an hour per account, 30 per IP address.
An authorized user needs the View emails sent to the account permission.
delete (client)
Section titled “delete (client)”POST /api/client/email/delete
Deletes one email from the client’s email history.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The email’s ID. |
Returns: true
Errors:
- Email not found (code 404)
It is gone for staff too. An authorized user needs the View emails sent to the account permission.

