CompanyInvoiceDelivery

Send an invoice by email

Sends the invoice by email, attaching its PDF by default. When no recipient is given, the addresses configured on the customer are used.

post/v1/companies/{company_id}/invoices/{invoice_id}/send

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/invoices/{invoice_id}/send
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

recipientsEmail[]

Recipients of the email. When omitted, the invoice's email_config recipients apply, then the customer's billing_emails, then the customer's email.

ccEmail[]

CC recipients. Copied addresses count as recipients of the message: they are subject to the same sending restrictions and to the same quota as the addresses in recipients. When omitted, the CC addresses configured in the sender's email defaults apply; send an empty array to deliver the message without any copy.

subjectstring

Email subject (optional, if not specified uses a default)

messagestring

Custom message (optional, added before standard message)

attach_pdfboolean
attach_source_invoicesboolean

Attach a ZIP archive (suplidos_<invoice-number>.zip) containing the PDFs of the source invoices referenced by the invoice's SUPLIDO consolidation lines (source_invoice_ids). Each PDF inside the ZIP is named <invoice-number>_<issuer-tax-id>.pdf. Requires attach_pdf: true (the ZIP accompanies the invoice PDF). Access to sources owned by managed accounts is re-checked at send time with the same rules as issuing; the request fails with an actionable error — never a partial ZIP — if the invoice has no consolidation sources (ATTACH_SOURCE_INVOICES_NO_SOURCES), a source is not reachable (ATTACH_SOURCE_INVOICE_UNAVAILABLE), a source has no generated PDF (ATTACH_SOURCE_PDF_MISSING), or the ZIP exceeds the size limit (ATTACH_SOURCE_ZIP_TOO_LARGE).

language'es' | 'en' | 'ca'

Supported languages: es Spanish, en English, ca Catalan.

Example request

{
  "recipients": [
    "user@example.com"
  ],
  "cc": [
    "user@example.com"
  ],
  "language": "es"
}

Response

Email sent successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "email_id": "550e8400-e29b-41d4-a716-446655440000",
    "sent_to": [
      "user@example.com"
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.