Files
Set emailed-report inclusion
/a/File_setIncludeInMailReport
Add or remove the metadata flag that includes a linked file with an emailed report.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible | Yes | Positive 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. |
val | Integer-compatible | No | Truthy 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
| 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: 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_editedor 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
Files_getDataTableexposes the flag asmetaIncludeInEmail.- File identifiers and downloads explains file ID, resource ID, type enum, stored URL and the different content response shapes.