When to use this endpoint

Use for the CRM2 mail-history table, then read individual mail IDs for detail or resend.

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
groupByNative list of mapped namesNoGroups the SQL rows by recognized mapped fields. Returned columns remain ordinary projections; counts still count matching records rather than groups. This wrapper adds no aggregate-safe projection validator.
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.
start / length / draw / isTable / limitInteger-compatibleNoTable defaults 0/10/0 for offset/page size/draw. isTable integer-converting to 0 returns {data:[...]} without draw/counts, optionally capped by positive limit. No route-owned maximum, negative-value clamp or length=-1 all-record sentinel exists.
orderBy / orderDesc / orderMapped name/direction or DataTables orderNoNamed orderBy/orderDesc take precedence; use asc/desc. Otherwise order[0].column minus one (clamped at zero) selects a projected mapped field; default first recognized projected field ascending. No stable ID tie-breaker. Unpaged mode has separate reference-date ordering.
searchValue / searchFieldText / mapped name or native listNoCase-insensitive substring LIKE; searchField defaults All. SQL % and _ retain wildcard meaning.
referenceDate / dateFrom / dateToMapped date field / relative integer day offsetsNoBoth bounds add inclusive day limits relative to today in the account timezone, with UTC fallback. These are day offsets, not absolute dates. Legacy offsetFrom/offsetTo hour/minute objects adjust datetime boundaries; date-only fields ignore them. timeRangeFrom enables inclusive hour filtering, upper timeRangeTo defaults 23; reversed bounds swap and the hour timezone falls back to Europe/London.
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.
Mail filtersMapped valuesNoid, cDate, cDateE, sentDate, sentDate_E, status, type, meta, customerID, customerType, userID, recipients, objType, objID and qmID.
triggeredBy / searchField=triggeredByNative {id} list / text searchNotriggeredBy collects positive user IDs from objects. Special triggeredBy text search resolves only the first active name match. If no match is found, no trigger-ID condition is added. Native trigger IDs are joined into a numeric IN list; zero/invalid IDs are skipped. The special name-search text is interpolated without SQL escaping, unlike ordinary mapped searches.
jobReference / subject / templateText / text / native ID listNojobReference matches saved Job references then meta.job_id (without a deleted-Job filter). subject searches both meta.subject and email_subject. template uses a native list against meta.template/email_template; empty lists can form invalid IN SQL. Scalar template values add no custom condition.
userID / userEmailFilterInteger / textNoAdds stored user_id equality OR substring matching of meta.creation.trigger_userid; optional email text adds recipients substring matching. The mapped userID filter is removed, so partial numeric matches can be included.
customerID / customerTypeMapped numeric selectionNoScalar customerID works normally. The UI {id} object-list form is flattened to a comma-separated string before mapped integer conversion; it is not a reliable multi-Customer filter.
invoiceID / objIDInteger-compatibleConditionalNonzero invoiceID selects (objID with mail type 1) OR (invoiceID with mail type 4), then removes objID/objType. Supply the linked Job ID as objID; invoiceID alone does not supply it.

Example request

$result = FM_api('Emails_getDataTable', ['fields'=>['id','cDate','recipients','type'],'start'=>'0','length'=>'10']);

Example response

{
  "data": [],
  "draw": 0,
  "recordsTotal": "0",
  "recordsFiltered": "0"
}

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.
  • Always overrides table sorting to cDate descending; client orderBy/orderDesc cannot change it. No stable ID tie-breaker is added. Counts are tenant mail counts, not the current user’s mailbox.
  • Table mode returns data/draw/recordsTotal/recordsFiltered; non-table mode remains a data envelope. There is no automatic sent-only/current-user/active-parent filter. Whole meta and recipients remain encoded text.

Side effects

  • Reads stored history only; does not check the mail queue or resend messages.

See it in Fieldmotion

CRM1

No direct generic CRM1 caller found; legacy Customer/User/Asset email tables use separate routes.

CRM2

Open the shared mail history or a Customer/User/Asset Email tab; table filters map to this route.

Related endpoints