Send to an e-mail recipient

When the receiver of an invoice is not on the Peppol network, BIAC Access point can deliver it by e-mail: the Peppol BIS Billing 3 UBL document is converted into a hybrid ZUGFeRD / Factur-X PDF (profile EN 16931, see Convert) and sent as attachment to the recipient e-mail address.

The sending is synchronous: a 200 OK response means that the message has been accepted by the mail server. It does not guarantee that the message has reached the recipient mailbox.

Prerequisite

The UBL document must meet the same requirements as for the conversion, in particular:

  • be a Peppol BIS Billing 3 Invoice or CreditNote, having as supplier the company linked to the API key;
  • contain the invoice PDF as its first embedded attachment. The other embedded attachments are kept as annexes of the Factur-X PDF;
  • respect the Peppol BIS 3.0 validation Rulesopen in new window.

Send by API

Request

  • URL : /document/send/mail
  • Method : POST
  • Headers:
    • x-api-key: THE API KEY
  • Max size: 50 MB
  • Body:
{
    "xmlBase64": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM9...",
    "recipientEmail": "invoices@buyer.de",
    "recipientName": "Käufer GmbH",
    "recipientEmailCc": ["accounting@buyer.de"],
    "mailSubject": "Rechnung 1122334455",
    "mailBody": "<p>Sehr geehrte Damen und Herren,</p><p>anbei unsere Rechnung.</p>",
    "clientReference": "MY-REF-001"
}
  • xmlBase64: The UBL document, base64 encoded
  • targetFormat (optional): The format of the delivered document. Only available value, and default: ZugferdEn16931
  • recipientEmail (optional): The recipient e-mail address. By default, the buyer contact e-mail of the document (cac:AccountingCustomerParty/cac:Party/cac:Contact/cbc:ElectronicMail). A single address is expected, without display name.
  • recipientName (optional): The display name of the recipient. By default, the buyer name of the document (cac:PartyLegalEntity/cbc:RegistrationName, else cac:PartyName/cbc:Name).
  • recipientEmailCc (optional): The copy recipients, 5 at most. Duplicates, and addresses equal to the recipient, are removed.
  • mailSubject (optional): The subject of the message, without line break. See default content.
  • mailBody (optional): The HTML body of the message, inserted as is. See default content.
  • clientReference (optional): Your own reference, returned in the response

Success Response

  • Code : 200 OK

Content exemple

{
  "transactionId": "fe7f3e0b-ce92-4b78-9f07-216cad3ca98a",
  "transactionStatus": "Success",
  "clientReference": "MY-REF-001"
}
  • transactionId: The UUID of the sending, used to retrieve the sent document (see Get documents send) and to give to the support in case of problem.
  • transactionStatus: Success

The converted document is not returned. Validation warnings, if any, do not prevent the sending and are not returned.

If the mail server refuses some copy recipients but accepts the recipient, the sending is a success.

Error Response

  • Code: 400 Bad request

The document or the request is rejected and nothing is sent. The message property starts with an error code, followed by a description.

Content exemple

{
  "transactionId": "e7d8b208-003f-4eb6-81d4-896e16fd8e89",
  "transactionStatus": "Failed",
  "message": "NO_RECIPIENT_EMAIL: No recipient address: provide recipientEmail or the buyer contact e-mail (AccountingCustomerParty/Party/Contact/ElectronicMail).",
  "clientReference": "MY-REF-001"
}

As for the conversion, the schema and business rules errors are detailed in xmlSchemaErrors and ublValidation.errors (see Convert).

  • Code: 401 Unauthorized

ApiKey incorrectly configured or invalid.

  • Code: 500 Internal Server Error

The conversion failed (CONVERSION_FAILED), or the mail server did not accept the message (SEND_FAILED). Please contact the support with the transactionId.

WARNING

When the mail server does not answer in time, the response is SEND_FAILED with the description delivery uncertain: the message may have been sent anyway. Check with the recipient before sending the invoice again.

Error codes

CodeHTTPDescription
UNSUPPORTED_TARGET_FORMAT400targetFormat has an unknown value.
INVALID_XML400xmlBase64 is missing, empty or is not well-formed XML.
INVALID_BASE64400xmlBase64, or the content of an annex, is not valid base64.
SCHEMA_VIOLATION400The document is not a UBL BIS Billing 3 Invoice or CreditNote, or does not respect the UBL schema. Details in xmlSchemaErrors.
SUPPLIER_MISMATCH400The supplier of the document is not the company linked to the API key.
NO_EMBEDDED_PDF400The document has no embedded attachment.
PDF_NOT_FIRST_ATTACHMENT400The first embedded attachment is not a PDF.
NO_RECIPIENT_EMAIL400No recipient address (neither recipientEmail nor buyer contact e-mail), an invalid recipient or copy address, or more than 5 copy recipients.
INVALID_MAIL_CONTENT400mailSubject contains a line break.
SEND_FAILED400The message exceeds the maximum size accepted by the mail server (38 MB once encoded, about 27 MB of PDF).
EN16931_VIOLATION400The document violates an EN 16931 or Peppol business rule. Details in ublValidation.errors.
CONVERSION_FAILED500Technical error during the conversion.
SEND_FAILED500The mail server refused the message or the recipient, or did not answer in time.

The controls are done in this order: target format, reading of xmlBase64, document type, supplier, invoice PDF, annexes, recipients, subject, size, then UBL schema and business rules. A rejected document is never sent.

The error descriptions never contain the e-mail addresses: an invalid copy recipient is identified by its rank in recipientEmailCc (starting at 1).

Message

Sender

The message is sent from the BIAC Log generic address noreply@biaclog-peppol.eu, or from the custom sender address of the company. The display name is the seller name of the invoice (cac:PartyLegalEntity/cbc:RegistrationName, else cac:PartyName/cbc:Name).

The Reply-To of the message is the seller contact e-mail of the invoice (cac:AccountingSupplierParty/cac:Party/cac:Contact/cbc:ElectronicMail), so that the recipient answers directly to the issuing company.

The mailToRespond address of the company receives a blind copy of every message (see Blind copy).

Default content

Without mailSubject, the subject is Rechnung <number> von <seller name> (Gutschrift for a credit note).

Without mailBody, the body is a German template built from the document: invoice number and date, due date, payable amount, then the seller name, address, VAT number and contact.

When the message is sent from the generic address, the mention Diese E-Mail wird im Auftrag von <seller name> versandt. is added at the end of the body, including a custom mailBody. It is not added with a custom sender address.

A plain text version of the body is generated from the HTML.

Attachment

The ZUGFeRD / Factur-X PDF is attached under the name <invoice number>.pdf (characters not allowed in a file name are replaced by _), or <transactionId>.pdf if the number cannot be used.

Tracking

The sendings by e-mail are listed with the other documents sent by the company (see Get documents send), successful or not. The receiver is the recipient e-mail address.

When the documents backup is enabled for the company, Get by id returns the sent ZUGFeRD PDF (application/pdf), or the submitted UBL when the conversion did not succeed.

Schemas

SendMailResponseModel

{
  "transactionId": "STRING",
  "transactionStatus": "STRING",
  "message": "STRING",
  "clientReference": "STRING",
  "xmlSchemaErrors": [
    {
      "context": "STRING",
      "errorMessage": "STRING",
      "xpathTest": "STRING"
    }
  ],
  "ublValidation": {
    "errors": [
      {
        "context": "STRING",
        "errorMessage": "STRING",
        "xpathTest": "STRING"
      }
    ],
    "warnings": [
      {
        "context": "STRING",
        "errorMessage": "STRING",
        "xpathTest": "STRING"
      }
    ]
  }
}

Properties without value are not returned. See ResponseValidationModel for the description of the properties.

Last Updated: