Jobs: scheduling and lifecycle
Send a job cancellation notification
/a/Jobs_emailCancelled
Attempt the configured cancellation emails for one stored job without changing its status.
When to use this endpoint
Use after a separate confirmed cancellation when reproducing the Jobs-list notification flow. The plural namespace still takes a single id.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login and adds no page/role-permission guard.
The primary job selection is tenant-scoped. Cross-tenant follow-ups, where described, use persisted outsourcing context.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Positive active job ID. Does not check that status is Cancelled; no recipients/template/body overrides are read from the request. |
Example request
$result = FM_api('Jobs_emailCancelled', ['id' => '1042']);Example response
{"ok":1}Absent/disabled job_on_cancel returns ok without sending. Enabled sending requires a positive mail acknowledgement with ok and ID; this confirms queueing, not inbox delivery.
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"} | Missing/nonpositive ID. |
{"error":"Job not found!"} | Missing/deleted job. |
{"error":"No valid Email"} | Enabled notification has no syntactically valid recipients after normalization. |
{"error":"Cancellation email delivery was not confirmed; check mail history before retrying."} | Queue response is absent/malformed, contains error, or lacks positive ok/ID. No automatic resend. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Requires login only. Uses notification_types.job_on_cancel enabled/template/text settings; the job-created notification gate is not consulted.
- Form-based selection starts with template, then configured default_template, and takes the FIRST rule whose numeric form_id matches the job and whose template_id is positive. Unmatched forms retain the default; unrelated/later rules cannot override it.
- email_customer resolves the direct active customer or the active asset's owner, not its customer-type location. email_user applies only to tenant-user type 0 and active user rows; email_creator also resolves an active user.
- email_other can contain comma/newline-separated addresses. All sources are trimmed, syntax-validated and deduplicated case-insensitively, then sent in ONE type-2 mail request. No valid recipients returns No valid Email before queueing.
- Does not require Cancelled status or change the job. Cancellation in CRM remains a separate saved-status request.
- No recipient pagination/limit or idempotency key. A failed/uncertain acknowledgement is returned for mail-history review without an automatic replay.
Side effects
- Attempts one type-2 Core_mail request with job_on_cancel provenance and the configured body/template. Does not edit status, delete/unassign the job, add mobile-removal markers or add an explicit job-history row.
See it in Fieldmotion
CRM1
Change a row's status to Cancelled in the Jobs list. pageJobs.js calls Job_setStatus first and then Jobs_emailCancelled as a second request.
CRM2
Jobs module status edit first performs a mapped update, then sends Jobs_emailCancelled and separately restores stock sources. These requests are not atomic.
Related endpoints
Job_setStatusincludes the extra single-job transition follow-ups.Jobs_statusSetcollects per-job transition errors.Jobs_emailRemoveduses current context for standalone removal mail.