Fieldmotion API Getting started

Email imports: configuration and diagnostics

Patch mapped task email-import configuration fields

POST /a/ImportTasksEmail_updateData

Patch mapped task email-import configuration fields

When to use this endpoint

Patch mapped configuration fields, as used by CRM2’s shared editing machinery and its task-type picker. These camel-cased keys differ from the legacy ImportTasksEmail_save payload.

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
idInteger or native arrayYesRequired positive integer or native array of positive integers. The helper validates and preflights every target, removes duplicate IDs, and commits changed global rows in one transaction. A JSON list string is not decoded. An empty native array is a no-op.
regexpsString or native array/objectNoJSON text or native structured data containing rows [pattern,replacement,destination,stripHtml]. Patterns require PCRE delimiters; SUBJECT: selects the subject. The worker skips blank, invalid, and nonmatching patterns, performs one replacement, and ignores a result identical to the actual input. A truthy fourth item strips HTML. The save does not validate rule semantics.
formIDIntegerNoDefault form_id. Numeric input is coerced with intval(); existence and Form compatibility are not checked.
sampleEmailStringNoReplaces stored sample_email; does not process it.
formByRegexpStringNoMaps to form_by_regexp, a job-Form name extraction PCRE. There is no regex validation.
spreadsheetsString or native array/objectNoSpreadsheet rules are JSON text containing rows [sheetNumber, columnLetters, rowNumber, destination]. Sheet and row numbers are one-based. The worker reads XLS/XLSX attachments, uses uppercase column letters through its legacy index helper, and can overwrite an earlier body-rule value with a spreadsheet value.
regexpsTableString or native array/objectNoMaps to regexps_table; job attachment-table rules are rows [pattern,replacement,tableFormID,columnName].
regexpsTableDelimitersString or native array/objectNoMaps to regexps_table_delimiters, with literal delimiter keys start, end, item_start, item_end.
nameStringNoLabel text, at most 64 bytes; blank is allowed. Unlike the focused setter, this mapped workflow does not trim or reject "0".
notesString or native array/objectNoReplacement note text or native array/object (JSON-encoded). Maximum 65535 bytes after encoding. No note-entry merge; blank is allowed.
metaTaskTypeIntegerNoNested meta.type_id, coerced with intval(); preserves other metadata properties. No task-type existence check. This task map does not expose sampleEmailImport.

Example request

$result = FM_api('ImportTasksEmail_updateData', [
	'id' => '1042',
	'metaTaskType' => '7',
]);

Example response

{"ok":1}

Changed scalar or bulk writes return {"ok":1}. A scalar no-op returns {"warning":"No Change."}; a bulk no-op returns {"ok":1}. Unknown or null mapped values do not create a write.

Every bulk target is validated and read before any changes. A missing/foreign/wrong-type target or failed global write aborts the transaction: there is no committed prefix and no updatedIds/failedId response.

Tenant history is recorded after global commit, once per changed row. History failure returns saved:1 and a warning, not an error suggesting that the global write was rolled back.

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: id"}No non-null id is supplied.
{"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"}The request includes ownerID, recipient, type, lastEdited, noRecord, or noRecordCustom. These controls are not writable through mapped configuration updates.

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

Behaviour and edge cases

  • This call changes configuration only. It does not fetch a mailbox, parse a message, or synchronously create a customer, job, or task. The background email processor consumes the stored configuration later; this API provides no processing-time guarantee.
  • Only recognized, non-null mapped values are considered. Unmapped parameters are ignored; null does not clear a mapped value. Numeric columns use integer coercion; text is bound as content and structured text values are JSON-encoded. No extraction-rule schema or Form/task-type existence validation is added.
  • The task worker reads meta.type_id, not the body-mapping columns. Changing mapped extraction rules does not make Tasks by Email use the customer/job extraction workflow.
  • Use native arrays for ID batches and structured text values, as CRM2 does. The signing helper’s http_build_query() preserves native nested form keys; do not JSON-encode the ID selector. JSON encoding is appropriate for rule columns accepted as text, not for helper selectors.
  • Primary ID selection is immutable, and ownerID, recipient, type, lastEdited, noRecord and noRecordCustom are explicitly rejected. The server owns identity, routing, dispatch type and edit timestamps; audit suppression is not accepted.

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_updateData was found. The legacy Tasks by Email screen uses focused setters and ImportTasksEmail_save, with ImportFilter_setMetaField for task type.

CRM2

Tasks by Email saves structured Notes with ImportTasksEmail_updateData. Type changes also send metaTaskType, including native ID arrays for bulk changes. Filter browser requests for the exact mapped route.

Related endpoints