Fieldmotion API Getting started

Email imports: configuration and diagnostics

Edit notes on a task email-import configuration

POST /a/ImportTasksEmail_setNotes

Edit notes on a task email-import configuration

When to use this endpoint

Store an administrative text note about the configuration. These notes describe the configuration; they are not the body of an imported email or notes added to an imported business object.

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
idIntegerYesPositive global configuration ID. The shared mutation helper requires a complete positive integer value, not a malformed or fractional string accepted only by intval. Missing, zero, negative, and invalid IDs are rejected.
valStringYesTrimmed, nonblank text, at most 65535 bytes. Empty text and the string "0" are rejected, so this focused endpoint cannot clear the note.

Example request

$result = FM_api('ImportTasksEmail_setNotes', [
	'id' => '1042',
	'val' => 'Rules maintained by the integration team.',
]);

Example response

{"ok":1}

Changed values return {"ok":1}. An unchanged trimmed value returns {"ok":"1","warning":"no change required"}, without changing the timestamp or history.

A committed global write whose later tenant history write fails returns success with saved:1 and a warning; do not replay it.

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: id"}Nonpositive ID, before authentication.
{"error":"missing or invalid parameter: val"}Missing, blank, or false-like trimmed text, before authentication.
{"error":"parameter val too long. max length 65535"}The trimmed value exceeds 65535 bytes, before authentication.
{"error":"Import By Email feature not enabled"}The account feature bit is disabled.
{"error":"that import does not exist"}No owned configuration was found.
{"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.

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

Behaviour and edge cases

  • Stores trimmed text literally, without merging note entries or transforming it into CRM2’s structured note array. Passing JSON text replaces the stored note text.
  • Blank text and "0" cannot clear notes through this focused setter. No-op comparison returns before writing. Use the mapped notes workflow for structured CRM2 notes.

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

In Imports → Tasks by Email, edit the Notes field. Filter for ImportTasksEmail_setNotes; the focused editor sends val.

CRM2

The Tasks by Email Notes editor uses ImportTasksEmail_updateData with structured notes, not this focused text setter. Do not assume the two note formats are interchangeable.

Related endpoints