Fieldmotion API Getting started

Invoices

Send a credit note by email

POST /a/CreditNote_sendEmail

Queue a credit-note email through the shared mail service and mark the credit note as emailed.

When to use this endpoint

Use this from the CRM2 Send Email widget after loading the note and choosing recipients/template content.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session and is scoped to the authenticated tenant.

The tenant setting accounting_credit_notes must equal 1. Otherwise the handler returns {"error":"Credit Notes are not enabled for this account"}.

Users whose legacy crm_access mask contains bit 64 are denied. The handler does not enforce the CRM2 pageCreditNotes role permission, ownership, or department scope.

Parameters

ParameterTypeRequiredDescription
idPositive integer-compatibleYesActive credit-note ID.
emailNon-empty stringYesPrimary recipient. Syntax is not validated.
email_additionalNewline-separated stringNoAdditional recipients. Blank lines and duplicates are not removed by this handler.
subject / textStringsYesKeys must be present; empty strings are accepted.
email_templateInteger-compatibleNoTemplate ID passed to mail; defaults to 0.

Example request

$result = FM_api('CreditNote_sendEmail', [
	'id' => 311,
	'email' => 'accounts@example.test',
	'subject' => 'Credit note CN-1042',
	'text' => 'Please find your credit note attached.',
]);

Example response

{
  "ok": 1,
  "credit_note_id": 311
}

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":"credit note does not exist"}The ID is absent or soft-deleted.
{"error":"Credit Note email could not be queued: ..."}The mail service explicitly rejected the request; the note is not marked emailed.
{"error":"Credit Note email queue response was uncertain. Check mail history before retrying."}The mail service did not confirm acceptance; inspect mail history before retrying because it may have accepted the message.

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 first active job linked through credit-note relation type 14 supplies job reference and assigned-user mail context. Relation ordering is unspecified.
  • Recipient strings are passed through to the mail service as supplied. The endpoint does not generate a PDF itself or accept the invoice attachment parameter.

Side effects

  • Calls the shared mail service with mail type 14 and records the exact legacy appointment_id key in mail metadata for job context. Only a positive queue acknowledgement updates email_sent and edit metadata, invalidates the credit-note cache, and writes email activity history. External mail acceptance and the local sent update are not one transaction.

See it in Fieldmotion

CRM1

No CRM1 credit-note mail flow was found.

CRM2

Open a saved credit note and choose Email. The shared Send Email widget loads CreditNote_get and submits this route.

Related endpoints