Skip to content

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.

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"
}
]
}

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:

true

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

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

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
}
]
}

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

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

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
  • 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_send call 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:

64

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.
  • Email template rendering error: Variable “” does not exist … (code 9999) for a custom template whose text uses a variable that only your template_send call gives, without a default (see template_create).

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:

true

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:

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

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

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

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

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.

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).

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.

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

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."
}
]
}

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.

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.

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 to and to_client cannot 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:

true

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)

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)

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.

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.

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.

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.

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.