Email history and previews
Filter email history
/a/Emails_getDataTable
Page stored mail history with UI-specific user, Job, subject and template filters.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
groupBy | Native list of mapped names | No | Groups 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. |
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. |
start / length / draw / isTable / limit | Integer-compatible | No | Table 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 / order | Mapped name/direction or DataTables order | No | Named 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 / searchField | Text / mapped name or native list | No | Case-insensitive substring LIKE; searchField defaults All. SQL % and _ retain wildcard meaning. |
referenceDate / dateFrom / dateTo | Mapped date field / relative integer day offsets | No | Both 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 / 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. |
Mail filters | Mapped values | No | id, cDate, cDateE, sentDate, sentDate_E, status, type, meta, customerID, customerType, userID, recipients, objType, objID and qmID. |
triggeredBy / searchField=triggeredBy | Native {id} list / text search | No | triggeredBy 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 / template | Text / text / native ID list | No | jobReference 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 / userEmailFilter | Integer / text | No | Adds 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 / customerType | Mapped numeric selection | No | Scalar 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 / objID | Integer-compatible | Conditional | Nonzero 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
| 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.
- 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
Email_getRequestedDetails— Continue the related read/write workflow.Email_resend— Submit stored history again.