Send invoice email to contractor

curl --request POST \
  --url https://api.altera.co/sales/invoice/send \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "invoiceId": 12345,
  "recipientFromSystem": true
}
'

{
  "result": "OK",
  "data": "Ok"
}

{
  "result": "Error",
  "errorMessage": "This tag cannot be deleted, it has been used in at least one invoice. You can disable it so it won't appear on the suggestion lists.",
  "errorMessagePL": "Ta kategoria nie może zostać usunięta ponieważ została użyta w przynajmniej jednej fakturze. Możesz ją zablokować aby nie pojawiała się na liście sugerowanych."
}

{
  "result": "Error",
  "errorCode": "KEY_EXPIRED",
  "errorMessage": "API key has expired"
}

POST

sales

invoice

send

curl --request POST \
  --url https://api.altera.co/sales/invoice/send \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "invoiceId": 12345,
  "recipientFromSystem": true
}
'

{
  "result": "OK",
  "data": "Ok"
}

{
  "result": "Error",
  "errorMessage": "This tag cannot be deleted, it has been used in at least one invoice. You can disable it so it won't appear on the suggestion lists.",
  "errorMessagePL": "Ta kategoria nie może zostać usunięta ponieważ została użyta w przynajmniej jednej fakturze. Możesz ją zablokować aby nie pojawiała się na liście sugerowanych."
}

{
  "result": "Error",
  "errorCode": "KEY_EXPIRED",
  "errorMessage": "API key has expired"
}

Required configuration and recipients

Configure the global reply-to address in Settings > Sales > E-mail messages. This address is used for replies to the email. It does not select the recipients or confirm delivery. Provide the invoice ID and one of the following:

A nonempty recipient array containing email addresses.
recipientFromSystem: true to load the contractor email addresses saved on the invoice.

When recipientFromSystem is true, contractor addresses take precedence over recipient. A contractor without an email address causes HTTP 400. Passing only invoiceId is insufficient.

Company email template and subject

If content is omitted, empty or whitespace-only, Altera loads the company invoice-send email template configured in Settings > Sales > E-mail messages and fills its placeholders:

Placeholder	Inserted invoice data
`%N`	Invoice number.
`%D`	Invoice number, gross amount, currency and due date in Polish.
`%EN`	Invoice number, gross amount, currency and due date in English.

Configure the template before omitting content. Without a configured template, the endpoint returns HTTP 400. To supply a different body for a single request, provide nonblank plain text or HTML in content. If topic is omitted, empty or whitespace-only, the standard subject is Faktura numer {invoiceNumber}. It is generated from the invoice number, independently of the company body template and the invoice document language. A nonblank topic overrides the standard subject.

This subject behavior requires the subject fallback fix to be deployed to the target environment. Older versions may return HTTP 500 when topic is omitted and replace a supplied nonblank topic with the standard subject. Until that environment is updated, supply a nonblank topic even when using the company body template; custom subjects are not preserved by the older version.

For example, after configuring reply-to and the invoice-send template, request the saved contractor recipients with this payload:

{
  "invoiceId": 12345,
  "recipientFromSystem": true
}

The resulting body uses the configured template, and the subject uses the standard format above. To override either value, supply content, topic or both. The fields are resolved independently.

Queue acceptance and QA delivery

HTTP 200 with "result": "OK" confirms that the email was accepted into the sending queue. Delivery runs asynchronously. The public API currently exposes no email-send history or delivery-status endpoint. The response and the invoice’s SENT status do not confirm receipt in the recipient mailbox. QA uses sandbox email routing: external recipient addresses are removed, so an address outside @altera.co does not receive the invoice. Configuring an external reply-to address does not bypass this rule. If there is no remaining Altera recipient, sandbox routing uses an Altera reply-to address when available, otherwise the technical sender address. To verify actual receipt and the attached invoice in QA, coordinate a test recipient address in the @altera.co domain with Altera support and supply it in recipient:

{
  "invoiceId": 12345,
  "recipient": ["qa-tester@altera.co"],
  "topic": "QA invoice test",
  "content": "<p>Please verify the attached test invoice.</p>"
}

Replace the illustrative address with the address agreed with support. Omit recipientFromSystem or set it to false so the explicit recipient is used. QA can verify request validation, queue acceptance and delivery to the agreed Altera address. It cannot verify delivery to an external recipient; that requires a separately coordinated production test.

Authorizations

Authorization

string

header

required

OpenApi Key created within Altera.app for a certain company

Body

application/json

Provide invoiceId and either a nonempty recipient array or recipientFromSystem: true. If topic is omitted, empty or whitespace-only, Altera generates the standard subject from the invoice number. If content is omitted, empty or whitespace-only, configure the company invoice email template before sending. Explicit nonblank values override these defaults independently. content accepts plain text or HTML. The company template configures the body; the standard subject is generated separately. See the endpoint guide for the older-version subject fallback limitation.

Option 1
Option 2

recipient

string<email>[]

required

Explicit email recipients. Required unless recipientFromSystem is true. Ignored when recipientFromSystem is true.

Minimum array length: 1

invoiceId

integer

required

ID of an invoice belonging to the company identified by the API token.

Required range: x >= 1

topic

string

Optional email subject. If omitted, empty or whitespace-only, generates Faktura numer {invoiceNumber}, independently of the company body template and invoice document language. A nonblank topic overrides the standard subject. Requires the subject fallback fix in the target environment; see the endpoint guide for the older-version workaround.

Maximum string length: 400

Example:

"New invoice #123"

content

string

Optional email body as plain text or HTML. If omitted, empty or whitespace-only, uses the company invoice-send email template with invoice placeholders expanded. Configure that template in Settings > Sales > E-mail messages first; a missing template returns HTTP 400. A nonblank value overrides the company template.

Maximum string length: 900000

recipientFromSystem

boolean

default:false

When true, load recipient addresses from the contractor saved on the invoice. Takes precedence over recipient. At least one contractor email address must exist.

Response

Email accepted into the sending queue. This confirms enqueueing, not delivery to the recipient mailbox.

result

enum<string>

required

Available options:

OK

data

enum<string>

required

Available options:

Ok

OpenAPI Documentation

Sales

Data export

Expenses

Configuration

Send invoice email to contractor

Required configuration and recipients

Company email template and subject

Queue acceptance and QA delivery

Authorizations

Body

Response

​Required configuration and recipients

​Company email template and subject

​Queue acceptance and QA delivery

Authorizations

Body

Response

Required configuration and recipients

Company email template and subject

Queue acceptance and QA delivery