Fieldmotion API Getting started

Invoices

Send an invoice by email

POST /a/Invoice_sendEmail

Queue invoice email through the shared mail service and record the invoice and every directly linked job as sent.

When to use this endpoint

Use this after collecting recipients and message content and, normally, generating or selecting the invoice attachment.

Authentication and permissions

Accepts an authenticated tenant CRM/API session or the legacy customer-portal tenant session. The legacy access-mask restriction applies.

Parameters

ParameterTypeRequiredDescription
idPositive integerYesActive invoice ID.
email / email_additionalEmail string / newline-separated stringPrimary requiredPrimary recipient and optional additional recipients. The handler does not validate email syntax or remove blanks/duplicates.
subject / textStringsYesMail subject and body; empty values are accepted when the keys are present.
email_templateIntegerNoTemplate ID copied into the mail request metadata.
invoiceAttachmentsArrayNoAttachment descriptors copied into mail metadata when non-empty.
set_draft_to_invoicedInteger-compatibleNoWhen 1, transitions a Draft invoice to Invoiced through Workflow status handling before queuing mail.

Example request

$result = FM_api('Invoice_sendEmail', [
	'id' => 981,
	'email' => 'accounts@example.test',
	'subject' => 'Invoice INV-981',
	'text' => 'Please find your invoice attached.',
]);

Example response

{
  "ok": 1,
  "invoice_id": 981
}

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":"invoice does not exist","line":...}The invoice is absent or deleted; the legacy response also exposes a source line number.
{"error":"Invoice email could not be queued: ..."}The mail service explicitly rejects the request.
{"error":"Invoice email queue response was uncertain. Check mail history before retrying."}The mail service does not return a confirmed acknowledgement; the caller should check mail history before retrying to avoid a duplicate.

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 direct linked job supplies job reference and assigned-user mail context; the exact legacy link field is used only as a fallback when no relation exists.
  • Success and sent timestamps require an explicit ok acknowledgement from the mail service.

Side effects

  • May transition Draft to Invoiced before attempting to queue mail. That status transition is not rolled back if queueing fails. After confirmed queueing, the endpoint sets invoice_sent on every directly linked job and sets invoice email_sent.

See it in Fieldmotion

CRM1

Invoice, Customer Invoice, Asset Invoice, Job mail, and shared Send Email dialogs use this route.

CRM2

The shared Send Email widget uses this route for single and bulk invoice sending.

Related endpoints