Fieldmotion API Getting started

Email imports: configuration and diagnostics

Create or save a task email-import configuration

POST /a/ImportTasksEmail_save

Create or save a task email-import configuration

When to use this endpoint

Create a routing address for Tasks by Email, then set its label, notes, and task type through separate calls. This endpoint is not a task creation API.

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
idIntegerNoUse 0 to create a new filter; customer/task calls default to zero when omitted. An existing positive integer updates only an owned row of the same family. Negative, fractional, blank, and malformed values are rejected. Job saves still require the id key.

Example request

$result = FM_api('ImportTasksEmail_save');

Example response

{"ok":1,"id":1042}

Success contains integer ok and the newly inserted or updated integer id. Insert, owner lookup, update, and global feature-marker failures are reported explicitly rather than returning null or a failed insert ID under success.

Missing, foreign-owned, and wrong-type existing IDs are errors. The global configuration and feature marker commit together. A later tenant-history failure adds saved:1 and a no-replay 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":"Import By Email feature not enabled"}The account feature bit is disabled.
{"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.

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.
  • Creation assigns the authenticated owner and task type 2; save also advances the server edit timestamp. Supplied extraction rules, sample content, Form IDs, labels, and notes are ignored. The task worker uses the email subject and plain body, matches a customer by sender email, and reads task type from meta.type_id; it is not driven by these body-extraction mappings.
  • Configure a task type separately with the mapped metaTaskType field or the focused metadata endpoint used by CRM1. The save neither validates a task type nor sends a task notification.
  • The routing address is generated only on insert. An existing filter of another type is rejected rather than retyped.

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.
  • Creates a cryptographically random 32-character routing token only on insertion. The recipient address is the token at import.fieldmotion.com.
  • On creation, sets global employers.features_used bit 4 in the same checked global transaction as the new filter.

See it in Fieldmotion

CRM1

In Imports → Tasks by Email, create an entry. Filter for ImportTasksEmail_save: creation sends no mapping payload. The Type picker later uses ImportFilter_setMetaField.

CRM2

In Tasks by Email, create an entry and filter for ImportTasksEmail_save. Type and notes changes use ImportTasksEmail_updateData afterwards.

Related endpoints