Jobs: scheduling and lifecycle
Send a job-removal notification
/a/Jobs_emailRemoved
Attempt the configured removal notification using the job's current stored recipient context.
When to use this endpoint
This standalone route sends notification only; it does not unassign or delete. For an old-assignee removal notification during reassignment, use Job_setUserIdAndType(email_removed=1) instead.
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. No old-user ID or assignment snapshot is accepted by this handler. |
Example request
$result = FM_api('Jobs_emailRemoved', ['id' => '1042']);Example response
{"ok":1}Absent/disabled job_on_remove 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":"Removal 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_remove 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.
- Standalone calls read the CURRENT assignee, with no old-user request override and an empty assignment snapshot. Job_setUserIdAndType(email_removed=1) instead supplies the previous row and typed old/new snapshot.
- 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_remove 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
No direct standalone browser caller remains. The Jobs User picker sets email_removed=1 on Job_setUserIdAndType, which supplies the previous job row and typed assignment snapshot to the same PHP mail helper.
CRM2
No direct standalone caller was found. Timeline assignment uses the typed setter without email_removed; do not assume every reassignment sends this notification.
Related endpoints
Job_setUserIdAndTypehandles typed outsourcing handover.Jobs_emailCancelledqueues cancellation mail separately.Job_deletedeletes one job through checked local cleanup.