Fieldmotion API Getting started

Email imports: configuration and diagnostics

Use the legacy task email-import single-field editor

POST /a/ImportTasksEmail_updateField

Use the legacy task email-import single-field editor

When to use this endpoint

Edit one mapped content field through the CRM2 inline editor. Customer and task routes now share the same checked, global, owner/type-scoped implementation; the former duplicate global helper declarations have been removed.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler calls Core_requireLogin(); it has no separate page, administrator, or role-permission check.

The account must have Import By Email enabled (employer|features bit 32768). There is no separate page, administrator, or role-permission check in these handlers.

The shared mutation helper selects the global database explicitly and locks the authenticated tenant owner and selected configuration rows. Every target must belong to that tenant and match this route’s configuration type: 0 job, 1 customer, or 2 task. Missing, foreign-owned, and wrong-type targets return the same that import does not exist error (the capture setter retains its dedicated not-found message).

Parameters

ParameterTypeRequiredDescription
id / idsInteger or native arrayYesRequired positive integer or native array of positive integers. id takes precedence over ids. Every target must be owned and match this family; duplicate IDs are removed and writes are transactional. JSON list strings are not decoded.
fieldStringYesExact writable mapped content key listed below. Primary id, ownerID, recipient, type, and lastEdited are protected rather than editable.
valScalar or native array/objectYesRequired non-null replacement. Text strings are bound without storing SQL escaping; native structured text is JSON-encoded, and numeric mapped values are integer-converted. Names are limited to 64 bytes and notes to 65535 bytes.
subFieldStringNoLegacy one-level JSON editing control. Requires exactly one selected ID; decodes the selected field as JSON or starts from an empty object when invalid, then sets this property. It is not a validated field-schema path.

Example request

$result = FM_api('ImportTasksEmail_updateField', [
	'id' => '1042',
	'field' => 'name',
	'val' => 'Website enquiries',
]);

Example response

{"ok":1}

Changed writes return {"ok":1}. A single selected unchanged value returns {"ok":"1","warning":"no change required"}. Multiple IDs with no changes return {"ok":1}.

The helper explicitly routes to the global table and checks persistence. A failure cannot be reported as success; bulk validation/write failures roll back the entire global batch. Later history failures remain committed-success warnings.

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":"Import By Email feature not enabled"}The account feature bit is disabled.
{"error":"missing or invalid parameter: field"}Missing/null field.
{"error":"missing or invalid parameter: val"}Missing/null replacement.
{"error":"missing or invalid field"}The field key is not in this family’s map.
{"error":"missing or invalid parameter: id/ids"}Neither selector is present.
{"error":"Cannot update multiple id on json format."}subField was supplied for a selection other than exactly one ID.
{"error":"that import does not exist"}No row of this family owned by the authenticated tenant was found. Bulk edits preflight every selected row before writing.
{"error":"email import write failed"}A checked global write or insert-ID retrieval failed; the global transaction is rolled back.
{"error":"email import read failed"}The checked lookup failed; no configuration write is committed.
{"error":"email import transaction failed"}Beginning or committing the global transaction failed. Inspect the configuration before retrying an uncertain commit.
{"error":"read-only field: KEY"}id, ownerID, recipient, type, or lastEdited was selected for editing.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Writable content keys: regexps, formID, sampleEmail, formByRegexp, spreadsheets, regexpsTable, regexpsTableDelimiters, name, notes, metaTaskType. Column meanings are listed by the mapped updateData endpoint.
  • Bulk metaTaskType edits on the task route now decode, update, and re-encode meta.type_id separately for each selected owned row, preserving unrelated metadata. The native ID list is one checked global transaction.
  • A single-ID subField edit decodes the selected text field as JSON (falling back to an empty object) and sets one property using the original value, not SQL-quoted text. It is not a full schema-aware JSON patch.
  • Both route files can be loaded in one PHP request without helper redeclaration. Changed writes automatically advance last_edited and queue one history entry per changed target.

Side effects

  • The primary configuration write uses checked global persistence, advances Unix-seconds last_edited, and requests import_filters cache invalidation. A changed write and any global feature-marker update commit together; a failure rolls back the global transaction.
  • Change history is written to the authenticated tenant after the global commit, once per changed configuration. These are separate database contexts, not an atomic cross-database audit. If history fails, the committed result includes saved:1 and a warning to avoid replaying the write. For a SQL-string deletion response, the warning result is an object with ok:1 and the original string under result.
  • No mailbox is fetched and no business object is imported synchronously by this configuration mutation.

See it in Fieldmotion

CRM1

No direct CRM1 caller for ImportTasksEmail_updateField was found. Tasks by Email uses the focused Name/Notes setters and save route instead.

CRM2

In Tasks by Email, edit the Name cell. The shared display-style widget assigns ImportTasksEmail_updateField as the default field-set route from the table prefix. Filter browser requests for that exact function; the Notes editor uses updateData instead.

Related endpoints