Embed and Email ZUGFeRD API Reference

Code Example

curl -X POST https://api.invoicexml.com/v1/embed/zugferd/email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "email.fromName=Acme Billing" \
  -F "[email protected]" \
  -F "[email protected]"

The pdf and xml parts are the same as on POST /v1/embed/zugferd; the email.* fields say who sends and who receives the invoice. Subject and message are left out here, so the defaults below are used.

Request

Content-Type: multipart/form-data

Full validation always runs on this route: there is no skipValidation field, so only an invoice that passes its rules is embedded and sent.

Email fields

Send each value as its own form field. For a second cc or bcc address, repeat the field.

A field that breaks one of these rules is answered with a 400 (errorCode 4002) before the invoice is embedded, and nothing is sent or billed.

Defaults

The number in the subject, the message and the attachment name comes from the invoice number (BT-1) and type code (BT-3) of the uploaded XML. Type codes 381 and 261 are credit notes and get the credit note wording.

The attachment is the ZUGFeRD PDF/A-3 made from your PDF and your XML. Characters that are not allowed in file names, such as the slash in 2026/0042, become a dash, so that number is attached as invoice-2026-0042.pdf.

The defaults are in English. To write to your customers in German, French or any other language, send your own subject and message. Both are sent exactly as given, so put the invoice number, amount or due date into the text yourself:

  -F "email.subject=Invoice 2026-0042 for October" \
  -F $'email.message=Hello Anna,\n\nyour invoice for October is attached.\n\nBest regards\nAcme Billing'

Headers

Response

{
  "status": "accepted",
  "messageId": "0100019a2f4c8e1b-3d7a9c52-6e1f-4b8d-a2c3-5f9e7d1b4a60-000000"
}

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errorCode": 4002,
  "valid": false,
  "detail": "The request failed validation with 1 error(s).",
  "errors": [
    {
      "rule": null,
      "layer": null,
      "line": null,
      "message": "The sender domain yourcompany.com is not one of this account's sending domains. Add it on the Verified email domains page of your dashboard first.",
      "btCodes": [],
      "fields": ["email.from"],
      "raw": null
    }
  ],
  "warnings": []
}

Error Reference

Every error uses the usual RFC 7807 envelope described on the status codes page, and no error sends an email. Errors of the invoice itself behave exactly as on POST /v1/embed/zugferd.

The other errors of the plain embed endpoint, for example 4017 for a profile identifier outside the specification, apply unchanged.

Billing

One credit per successful call, like every other endpoint. Not billed: calls refused because your plan does not include email (4020), sending is switched off (4021) or an email field is wrong (4002 on email.*), and sends that fail at delivery because the domain is not verified yet (4022), sending is paused (4021) or too many emails are going out at once (4019). Invoice validation errors are billed exactly as on POST /v1/embed/zugferd.