Fieldmotion API Getting started

Email imports: configuration and diagnostics

Capture the next job import message as a sample

POST /a/ImportJobsEmail_setSampleEmailImport

Capture the next job import message as a sample

When to use this endpoint

Arm or clear the capture flag before sending a representative message to the configuration’s routing address. Re-read the configuration after the background worker has consumed the message to retrieve the captured body.

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.
valIntegerNoDefaults to 0, then uses intval(). Only converted values 0 (disarm) and 1 (capture the next message) are accepted.

Example request

$result = FM_api('ImportJobsEmail_setSampleEmailImport', [
	'id' => '1042',
	'val' => '1',
]);

Example response

{"ok":1}

If the stored flag compares equal to the requested value, returns {"ok":1,"warning":"no change needed"} without a write. Missing/wrong-type/foreign filters retain import filter does not exist or is not yours.

A checked write failure is an error; a later history failure is a committed-success warning.

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 integer-converted ID, before authentication.
{"error":"import filter does not exist or is not yours"}No owned job-type filter was found.
{"error":"Import By Email feature not enabled"}The account feature bit is disabled.
{"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

  • This API call does not read the mailbox, send an email, or return a captured body. It changes the capture flag and server edit timestamp, then attempts tenant change history.
  • The worker captures the normalized body, with carriage returns and newlines replaced by spaces. It does not capture the subject into sample_email_subject. A message whose subject is exactly test email follows the worker’s earlier test branch and does not reach capture.
  • There is no pagination or batch selector. Capture timing depends on the background processor and arrival of a recognized message, not on this request returning.

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.
  • Later, the background worker overwrites sample_email from a received normalized body and resets the flag. It continues normal processing: capture still is not a dry run.

See it in Fieldmotion

CRM1

In Imports → Jobs by Email, change the Sample switch. Filter for ImportJobsEmail_setSampleEmailImport; the UI sends the row ID and the requested flag.

CRM2

In Jobs by Email, change the Sample switch and filter for ImportJobsEmail_setSampleEmailImport. Read ImportJobsEmail_getDetails after processing to inspect the sample.

Related endpoints