When to use this endpoint

Use File_setIncludeInMailReport from Job/related file options when the report-email workflow should attach this file.

Authentication and permissions

Normal API transport requires signed API-key fields or a logged-in CRM session and a tenant context. Session CSRF applies except for the dispatcher’s upload/download exceptions.

These handlers do not add general Files Add/Edit/Delete or file-owner role checks. UI visibility is not that protection. Configured team-scope entry checks are separate and may validate the linked record and its Edit permission before a handler runs; see the route-specific note below. This does not introduce CRM2 role requirements for ordinary CRM1 requests.

When department/team or Assigned Jobs Only scope is configured for the actor, the dispatcher adds record-scope checks. This is selected by account features/actor flags, separately from the CRM2-only Files View check; the existing TeamAccess entry guard has no CRM-version condition. Explicit id/ids values are checked against visible file records. Other filename-only selections or mapped-filter-only bulk mutations can be rejected for lacking an explicit scoped selection.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesPositive file ID. Use the tenant file-record ID returned by upload/list/detail calls. This is separate from type_id/typeId (the linked resource ID), and from the random token in a storage URL.
valInteger-compatibleNoTruthy stores meta.include_in_mail=1; false/absent removes the key.

Example request

$result = FM_api('File_setIncludeInMailReport', ['id' => '4821', 'val' => '1']);

Example response

{
  "ok": 1
}

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"}ID is non-positive.
{"error":"file not found"}The ID does not identify a live file.

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

Behaviour and edge cases

  • Malformed legacy metadata is normalized before the flag is changed. The update does not change last_edited or create an audit record. It affects later email assembly only when that workflow reads the flag.
  • No pagination applies to this write. A success acknowledgement from a dedicated metadata switch does not prove a checked database commit; those handlers do not inspect the update result. Generic mapped writers check their primary UPDATE but later history/notification work is separate.
  • val integer-converts before truth testing: zero, blank, absent or nonnumeric text removes the key; any nonzero integer sets numeric 1. No dependent portal/email flags or resource ownership are changed.

Side effects

  • Updates only the documented metadata key and invalidates the files cache. No file-content access, mail, audit or last_edited update is performed; the write result is not checked before returning ok=1.

See it in Fieldmotion

CRM1

Toggle attach/include in emailed report on Job, Task, or shared file tables.

CRM2

Job/file option menus call this route for the emailed-report switch.

Related endpoints