Update one email-template field

When to use this endpoint

Use EmailTemplate_updateField only for deliberate single-field bulk changes. Prefer EmailTemplate_save for normal editor work.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login and performs no additional page or role-permission check.

The read or write is limited to the authenticated tenant. Notice endpoints that say “current user” use the authenticated session user ID within that tenant.

Parameters

Parameter	Type	Required	Description
`id / ids`	Integer-compatible or native array	Yes	One ID or an array. `id` takes precedence; every value is integer-converted.
`field`	String	Yes	Exact mapped key from `id`, `name`, `body`, `archived`, `fromEmail`, `isDefault`, `subject`, `type`, `meta`, and `metaFormID`. The generic allowlist includes the primary `id` field.
`val`	Value compatible with field	Yes	Replacement value. An explicit blank string is accepted for text fields.

Example request

$result = FM_api('EmailTemplate_updateField', [
	'ids' => ['152004', '152005'],
	'field' => 'archived',
	'val' => '1',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id":"152004","archived":"0"},
    {"id":"152005","archived":"0"}
  ]
}

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":"missing or invalid parameter: field"}`	`field` is absent.
`{"error":"missing or invalid parameter: val"}`	`val` is absent.
`{"error":"missing or invalid field"}`	The field is not in the email-template map.
`{"error":"missing or invalid parameter: id/ids"}`	Neither ID parameter is present.

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

Behaviour and edge cases

The generic field allowlist includes dangerous fields. The route can change id, raw metadata, default state, sender, body, and archive state without the dedicated endpoint checks. External integrations should restrict it to a known-safe field set.

Rows that do not exist and rows already holding the value are skipped. If none need a change, the response is {"ok":"1","warning":"no change required"}.
metaFormID changes only meta.form_id and preserves other metadata keys.
The map has no last-edited field, so no timestamp is changed.

Side effects

Changed rows invalidate the email-template cache and produce one Core history event naming the mapped field and changed IDs.

See it in Fieldmotion

CRM1

No direct CRM1 production caller was found.

CRM2

No direct CRM2 production caller was found.

Related endpoints

EmailTemplate_updateData updates several mapped fields.
EmailTemplate_setFormId is the narrower form-metadata writer.