Send invoice via email

POSThttps://app.speybooks.com/api/v1/invoices/{id}/email

Send a sales invoice to the contact's email address, or to an override recipient. Only sales invoices can be emailed; purchase invoices and credit notes cannot, and a request for one is answered as not found.

Emailing a draft invoice issues it: the status transitions to sent and the sentAt timestamp is stamped (first issue only; it is never restamped). Because issuing requires a complete invoice, a draft whose lines are not all assigned to an account is rejected with a 400 before any email is sent. On a successful send of a draft, the status change, the ledger posting that issues the invoice (its double-entry journal), and the audit record are committed together, atomically, once the send has succeeded. Re-sending an already-issued invoice is permitted and does not alter its status or sentAt. A cancelled invoice cannot be emailed: the request fails with a 400 before any email is sent. An audit record is written for every successful send, capturing the recipient and invoice number.

All body fields are optional:

  • to: override recipient email (defaults to the contact's email address; if the contact has none and no override is provided, the request fails with a 400)
  • subject: override the email subject (defaults to "Invoice INV-XXXX from Org Name")
  • message: custom message rendered in a highlighted block above the invoice details

The email includes the organisation's details (name, address, VAT number), the recipient's contact details, issue and due dates, the line item table, the subtotal, VAT, and total summary, and any notes and terms on the invoice.

Email delivery is synchronous. If delivery fails, the request returns a 500 and the invoice status is not changed; the request is safe to retry.

Error responses:

  • 400 { code: "invalid_id" }: malformed or wrong-prefix ID
  • 400 { code: "unprocessable_entity" }: the invoice is cancelled, or it is a draft with one or more lines that have no account assignment (required before a draft can be issued)
  • 400 { code: "validation_error" }: no email address available (contact has no email and no to override)
  • 404 { code: "not_found" }: invoice does not exist, belongs to another organisation, or is not a sales invoice
  • 500 { code: "internal_error" }: email delivery failed; the invoice status is unchanged, retry the request

Idempotency: Not idempotent. Each call sends a new email and writes a new audit record, and a draft transitions to sent on the first successful send. Confirm before re-sending.

Path parameters

idstringrequired
Invoice ID (e.g., inv_42)

Body parameters

messagestringoptional
Custom message to include
subjectstringoptional
Override email subject
tostringoptional
Override recipient email

Response

200Invoice sent successfully. If the invoice was in draft status, it is automatically moved to sent.
Show response fields
idstring
Prefixed invoice ID (e.g. inv_42).
invoiceNumberstring
Invoice number (e.g. INV-0042).
sentTostring
Email address the invoice was sent to.

Error codes

400Invalid invoice ID format, or no email address available for the contact.
404Invoice not found, is not a sales invoice, or does not belong to this organisation.
500Email delivery failed. The invoice status is not changed. Retry the request.