Fieldmotion API Getting started

Customers

List customer email history

POST /a/Customer_emailsGetDT

Populate the customer Email History table with delivery state, recipients, templates, job references, and notification-source details.

When to use this endpoint

Use Customer_emailsGetDT for the CRM1 email-history panel on a customer. It resolves compatibility fields from several generations of mail metadata.

Use Customer_emailsGetDataTable only when a caller needs named, selectable mail fields across the tenant and will provide its own customer filters.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

ParameterTypeRequiredDescription
cidInteger stringYesPositive customer ID. The customer record is not checked for existence.
startInteger stringNoZero-based offset; defaults to 0.
lengthInteger stringNoPage size; defaults to 10.
drawInteger stringNoDataTables counter copied to the response; defaults to 0.
dateFromYYYY-MM-DD stringNoLower bound applied to mail creation date. A missing value or one that fails the digit-pattern check defaults to the server’s current date; calendar validity is not separately checked.
dateToYYYY-MM-DD stringNoUpper bound applied to sent date after adding one day. Missing or format-invalid input defaults to the server’s current date.
search[value]StringNoSubstring match against mail ID or the raw metadata JSON.
order[0][column]Integer stringNo0 ID, 1 created date, 2 sent date, 3 status, or 9 type; defaults to created date.
order[0][dir]StringNoLegacy inverted direction: desc produces ascending SQL order; other or omitted values produce descending order.

Example request

$emails = FM_api('Customer_emailsGetDT', [
	'cid' => '1088',
	'start' => '0',
	'length' => '25',
	'draw' => '8',
	'dateFrom' => '2026-09-01',
	'dateTo' => '2026-09-30',
	'order' => [['column' => '2', 'dir' => 'desc']],
	'search' => ['value' => 'service report'],
]);

Example response

{
  "draw": 8,
  "recordsTotal": "320",
  "recordsFiltered": "1",
  "data": [
    [["501","8841"], "2026-09-24 11:00:00", "2026-09-24 11:01:02", "2", "Service report", "JOB-7204", "17", "Job Report", "[\"ops@example.test\"]", "36", "", "Job completed", "36", "Job-completion notification"]
  ]
}

The 14 positions are [mail ID, queue-mail ID], created date, sent date, status, subject, job reference, template ID, type label, raw recipients JSON string, user ID, blank placeholder, trigger label, trigger user ID, and notification-source header.

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.
{"error":"missing or invalid parameter: cid"}cid is absent, zero, negative, or non-numeric.

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 query requires customer_type=0 and the requested customer ID. recordsTotal nevertheless counts every mail row in the tenant.
  • The date window is asymmetric: the lower bound compares cdate, while the upper bound compares sent_date. Unsent rows with NULL sent_date do not satisfy the upper comparison. The next-day boundary uses <=, so exactly midnight after dateTo is included.
  • Subject falls back from metadata subject to email_subject; template falls back from template to email_template. Missing recipients can fall back to metadata or the job customer’s email.
  • Type values map to Email, Job Report, Quote, Invoice, Purchase Order, Send Both, Signature, or Credit Note; unknown values fall back to Email.
  • Notification source is derived from current metadata first, then legacy creation.trigger_event; creator user ID comes from creation.trigger_userid.
  • The legacy search value is interpolated without escaping by this handler. External tools should send trusted plain text rather than expose it directly to untrusted input.

See it in Fieldmotion

CRM1

Open a customer and select Email History. Filter Network requests for Customer_emailsGetDT; changing the visible date range, search, sort, or page reloads it.

CRM2

A source search found no CRM2 caller for this legacy email-history table.

Related endpoints