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

ParameterTypeRequiredDescription
id / idsInteger-compatible scalar or native listNoid 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.
fieldsNative list of mapped namesNo for details; required for tablesDetails 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 filtersMapped scalars or native listsNoid, 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 / advanceSearchScalars, native lists or structured query controlsNoMapped 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

ResponseCondition
{"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