Read mapped task email-import configuration fields

When to use this endpoint

Project mapped values from owned task email-import configurations before a task-type edit. This is the mapped counterpart of the one-row raw detail call.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login but performs 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 global query always adds authenticated tenant owner and task type 2. Caller-supplied ownerID/type filters cannot remove those conditions.

Parameters

Parameter	Type	Required	Description
`fields`	Native array of strings	No	Native array of task-map keys. Defaults to all mapped fields. id is always included; invalid field names and non-string entries are rejected. JSON list text is not decoded.
`id / ids`	Integer or native array	No	Optional scalar/native array; id takes precedence and ID values are integer-converted by the details helper. Omitted or empty native selectors impose no ID restriction, but owner/type restrictions always remain. JSON list text is not decoded.
`order`	String or native array	No	Mapped field name or native array of names / `{id,dir}` objects. Directions must be literal `asc` or `desc`; malformed controls and unmapped names are rejected. No default order is imposed.
`mapped filters`	Scalar or native array	No	Mapped non-ID keys may supply exact filters: text request values are lower-cased and trimmed, arrays use IN, numeric scalars use intval. The server independently enforces the authenticated owner and task type.
`advanceSearch`	Native array	No	Optional native structured mapped rules with column/id, condition and value. Conditions: equal, notEqual, contains, greaterThan, greaterThanOrEqual, lesserThan, lesserThanOrEqual. AND/OR connectors and balanced special parentheses are validated. Raw where fragments, unknown columns, malformed values and grouping/order controls are rejected.

Example request

$rows = FM_api('ImportTasksEmail_getRequestedDetails', [
	'ids' => ['1042'],
	'fields' => ['id', 'metaTaskType'],
]);

Example response

[
	{"id":"1042","metaTaskType":7}
]

Returns a bare array in the requested mapped shape. Missing IDs are omitted, and no matches or failed row retrieval returns []. There is no total count or ok envelope.

Ordinary database numeric scalars remain strings. metaTaskType is projected from decoded meta.type_id and therefore follows the stored JSON scalar type, or is null when absent. Raw text mappings such as regexps, spreadsheets, and notes remain strings, not parsed rule/note arrays.

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"unsupported raw advanced search"}`	A rule includes a literal where fragment.
`{"error":"unbalanced advanced search"}`	Parenthesis markers are not balanced.
`{"error":"missing or invalid parameter: fields"}`	Fields are not a native array of valid mapped names.

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

Behaviour and edge cases

Readable/filterable mapped keys: id, ownerID, recipient, regexps, formID, sampleEmail, formByRegexp, spreadsheets, regexpsTable, regexpsTableDelimiters, type, name, lastEdited, notes, metaTaskType. These keys are readable/filterable, including server-owned read-only keys such as ownerID and lastEdited. Column meanings are described by the mapped write endpoint; this read does not accept sampleEmailImport or expose the whole meta field as a mapped key.
No pagination, limit, cursor, or active/deleted condition is added. Explicit selected IDs are important to avoid an unbounded owned-task result; ordering must be requested when needed.
A field projection restricts the response columns, not authorization. Configuration records from other tenants or types are excluded. Empty fields still returns id.
The read does not write history, invalidate caches, change timestamps, process email, or update task types. Native arrays in the example are sent as nested form keys by the signing helper’s http_build_query(); do not JSON-encode the ID or field lists because this helper does not decode them.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. Tasks by Email uses the legacy list and focused setters; task-type changes use ImportFilter_setMetaField.

CRM2

In Tasks by Email, select rows and choose Change Type. Filter for ImportTasksEmail_getRequestedDetails: the page requests fields: ["id","metaTaskType"] and the selected IDs, then checks that the current types match before showing the bulk type picker.

Related endpoints

ImportTasksEmail_getDetails: raw one-row read with an authenticated tenant-owner condition and feature gate.
ImportTasksEmail_updateData: mapped field meanings and the bulk task-type write.