Send invoice via email

POST https://app.speybooks.com/api/v1/invoice-email/{id}/email

Send a sales invoice to the contact's email address (or an override recipient). This is a multi-step operation:

  1. Validate the prefixed invoice ID (inv_*)
  2. Fetch invoice with contact and organisation details (filtered by organisation_id for multi-tenancy)
  3. Confirm the invoice is a sales type (purchase invoices cannot be emailed)
  4. Resolve recipient: override to field → contact email
  5. Fetch invoice line items ordered by ID
  6. Render branded HTML and plain text email bodies using organisation details (name, address, VAT number)
  7. Send via email service
  8. If invoice status is draft, transition to sent
  9. Write INVOICE_EMAILED audit log entry with recipient and invoice number

Authentication

Requires a valid JWT. The authenticated user must belong to the organisation that owns the invoice. Multi-tenancy is enforced via organisation_id filtering on the query.

State Transition

BeforeAfterCondition
draftsentEmail sent successfully
sentsentNo change (re-sending allowed)
paidpaidNo change (re-sending allowed)
overdueoverdueNo change (re-sending allowed)

Only the draft → sent transition modifies invoice state. Re-sending an already-sent invoice is permitted and does not alter the status.

Override Fields

All body fields are optional:

  • to — override recipient email (defaults to contact email)
  • subject — override email subject (defaults to "Invoice INV-XXXX from Org Name")
  • message — custom message rendered in a highlighted block above the invoice details

Side Effects

  • Email delivery — synchronous; returns 500 if send fails
  • Audit log — INVOICE_EMAILED entry with sentTo and invoiceNumber in details JSON, includes IP address
  • Status mutation — draft invoices promoted to sent

Email Content

The HTML email includes:

  • Organisation branding (name, address, VAT number)
  • Recipient contact details
  • Issue and due dates
  • Line item table (description, quantity, unit price, VAT rate, total)
  • Subtotal, VAT, and total summary
  • Optional notes and terms sections
  • Optional custom message in a highlighted block

Error responses:

  • 400 { code: "invalid_id" } — malformed or wrong-prefix ID
  • 400 { code: "validation_error" } — no email available (contact has no email and no to override provided)
  • 404 { code: "not_found" } — invoice does not exist, belongs to another organisation, or is a purchase invoice
  • 500 { code: "internal_error" } — email delivery failed

Idempotency: Not idempotent. Each call sends a new email, writes a new audit log entry, and (for drafts) transitions status. Clients should confirm before re-sending.

Path parameters

id string required
Invoice ID (e.g., inv_42)

Body parameters

message string optional
Custom message to include
subject string optional
Override email subject
to string optional
Override recipient email

Response

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

Error codes

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