Email history and previews
Preview an email template
/a/Email_preview
Expand literal template text using current business records without sending mail.
When to use this endpoint
Use the composer’s preview before an actual send endpoint. template is the template body text, not an email-template ID.
Authentication and permissions
Use signed API-key authentication or a logged-in CRM session on the account’s routed host. API keys act as their owner; normal session requests need dispatcher CSRF protection where configured. Tenant data is selected from the authenticated account.
The handler has no additional page-action/Role check. A CRM2 screen hiding a control does not add such a server guard, and CRM2 role names must not be assumed to apply to CRM1. The dispatcher has no dedicated object-scope mapping for this namespace.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
type | Integer-compatible | Yes | Checked for presence before login. Only type 1 enables the Job-report BODY/DOWNLOADLINKS block; other integer values still run available shortcode substitutions. |
template | Text | Conditional | Missing/native-null returns {ok:1,warning:"Template is empty"} before login. Present empty text is processed normally, not that warning. The handler does not fetch a saved template by ID. |
jobID / quoteID / opportunityID / invoiceID / creditNoteID / poID | Integer-compatible record IDs | No | Presence triggers record loading, so zero is not a no-op. Use the relevant context rather than mixing them: the loader processes these in that order, and later contexts can replace customer context. Job links can supply Quote, Invoice and Task context. taskID and customerID are not direct selectors here. |
body | Text | No | For type 1 and a BODY token, PHP-truthy body replaces the generated report summary and is HTML-escaped. The dummy report-download link is still included. |
Example request
$result = FM_api('Email_preview', ['type'=>'0','template'=>'Reference: {{JOB_REF}}','jobID'=>'7712']);
Example response
{
"template": "Reference: JOB-1042"
}
Application errors normally remain JSON responses with HTTP 200; inspect error/warning keys. Numeric driver values can be strings.
Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error":"missing or invalid parameter: type"} | type absent/null. |
{"error":"job does not exist"} | A supplied jobID has no active match. |
{"error":"customer does not exist"} | Derived Customer context is unavailable. |
{"error":"quote does not exist"} | A supplied quoteID is missing. |
{"error":"invoice does not exist"} | Supplied Invoice context is missing. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Returns only {template: renderedText}; it does not validate a complete outgoing message or return a sent/queued acknowledgement. Unknown or unavailable tokens can remain unchanged.
- Job context uses the active Job; Quote/Invoice/Purchase Order and related Customer lookups are not uniformly filtered for deleted records. Asset customers resolve through their location Customer or owner. Parent/grandparent Customer and linked Task context are loaded indirectly.
- date-format is read from the tenant; formatting collapses repeated format letters rather than using a general date-token converter. Job epochs use account-local time helpers, while PHP date output uses the running server context. JOB_DURATION depends on work-day-start/end and positive saved hours.
- Supported groups include JOB/USER/FORM/DEPARTMENT, recurrence (RECURRENCE and historical RECURRANCE spelling), ASSET, linked CONTRACT/QUOTE/PO/SUPPLIER, CUSTOMER/PARENT/GRANDPARENT, COMPANY, INVOICE, CREDIT_NOTE, OPPORTUNITY and linked TASK. Availability depends on loaded context, not the request type alone. Not every value is escaped consistently.
- Type 1 inserts a dummy download-job-report link. BODY is substituted with the supplied escaped body or a generated Job/Customer summary; if BODY is absent, DOWNLOADLINKS is replaced or the link block appended. These are preview links, not a real downloaded report.
Side effects
- Reads business records and site settings; no mail, notification, file or record mutation is performed by this preview.
See it in Fieldmotion
CRM1
No direct current CRM1 call found; legacy composers load templates separately.
CRM2
Open an email composer’s Preview tab; widgetSendEmail posts literal template text, body, type and relevant record IDs.
Related endpoints
EmailTemplates_list— Continue the related read/write workflow.EmailTemplate_get— Continue the related read/write workflow.Email_resend— Submit stored history again.