Email history and previews
Read selected email history records
/a/Email_getRequestedDetails
Project stored tenant mail records and derive display/source labels.
When to use this endpoint
Use mail-record IDs from an email table; these are neither template IDs nor notification-rule IDs.
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 |
|---|---|---|---|
id / ids | Integer-compatible scalar or native list | No | id takes precedence. Positive record IDs are the normal selection. Scalars integer-convert; encoded JSON list text is not decoded. On mapped details, omission or an empty native list adds no ID restriction, so supply another bounded filter deliberately. |
fields | Native list of mapped names | No for details; required for tables | Details default to all mapped fields. Unknown names are omitted; id is always included. JSON-encoded list text is not decoded. Whole JSON/text columns remain encoded strings, while nested metadata projections can decode values. |
Mail filters | Mapped scalars or native lists | No | id, cDate, cDateE, sentDate, sentDate_E, status, type, meta, customerID, customerType, userID, recipients, objType, objID and qmID. customerID is the linked Customer/Asset ID, distinguished by customerType. userID is the stored mail user, not an automatic actor filter. |
Mapped filters / order / advanceSearch | Scalars, native lists or structured query controls | No | Mapped filters combine with AND; lists use IN. Detail text filters are trimmed case-insensitive exact matches; table text filters use substring LIKE. Detail order accepts mapped names or {id,dir} descriptors. Structured comparisons use mapped columns, condition/value and optional andOr/special. These legacy wrappers do not add a strict query-control allowlist; raw advanced conditions are a trusted UI surface, not an integration SQL interface. |
Example request
$result = FM_api('Email_getRequestedDetails', ['id'=>['18'],'fields'=>['id','recipients','type']]);
Example response
[
{
"id": "18",
"recipients": "[\"office@example.test\"]",
"type": "2"
}
]
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. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- The current CRM status labels are 0 Preparing, 1 Sent, 2 Delivered, 3 Dropped, 4 Deferred, 5 Bounced, 6 Opened, 7 Clicked, 8 Spam Report and 9 Unsubscribe. These label stored history states; they are not a success acknowledgement from this read endpoint.
- Returns a bare row array for mapped details, not a single object; empty results are []. Whole metadata columns remain encoded strings. Database scalar types remain driver-dependent. The detail helper can also turn a failed database read into [], so it is not a distinct read-failure signal.
- When cDate/sentDate are selected and non-null, adds newCreatedDate/newCreatedTime or newSentDate/newSentTime using server PHP date formatting (uppercase M d, Y; h:i A). Narrow projections omit those extras.
- Non-null selected meta enables source enrichment: triggerEvent, notificationSource, notificationHeader, triggerUserID, recipient and template are derived when JSON decoding succeeds. template prefers meta.template over meta.email_template. meta itself stays encoded text. emailType is added inside the meta branch when type is selected and recognized: 0 Email, 1 Job Report, 2 Email, 3 Quote, 4 Invoice, 5 Purchase Order, 6 Send Both, 7 Signature.
Side effects
- Database reads only; no resend, preview rendering or mail delivery.
See it in Fieldmotion
CRM1
No direct generic CRM1 caller found; Customer/User/Asset email screens use their own table routes.
CRM2
Open a mail-history detail panel on Customers, Users, Assets or the shared mail-history widget; it requests selected fields through Email_getRequestedDetails.
Related endpoints
Emails_getDataTable— Continue the related read/write workflow.Email_resend— Submit stored history again.