MLS
TDD -->



MLS

Note: Support for MLS is currently only available on the testing environment. The planned release date for production is December 10

What is MLS

MLS stands for ‘Message Level Status’, and is a notification exchanged between Peppol Service Providers directly, in response to a transmitted document. It shows the status of document delivery at the receiving Service Provider: Delivered with confirmation (AP), Delivered without confirmation (AB), or Not Delivered (RE).

MLS is not a document that end-users create or send directly, it is purely communication exchanged between Service Providers.

For the full documentation of the MLS message and process, see the Peppol MLS Specification page.

The MLS process in ion-AP

Sending MLS messages

MLS messages are automatically sent if the sending Service Provider has a published MLS address on their SPID Peppol Identifier or to the identifier specified in the MLS_TO header field. If the header field FAILURE_ONLY is specified, an MLS is only sent if the status is RE.

An incoming document is first checked for validity according to the relevant XML Schema and Schematron rules. If the document is not valid, it is not delivered to the end-user, but an MLS RE message is sent to the sending service provider.

If it is valid, the document is delivered, and the MLS response code is determined based on the receive trigger(s) configured for the receiving organisation:

If there is (at least one) API_CALL, the trigger is executed, and the result of the first API_CALL trigger determines the MLS status:

  • If the call succeeds, the MLS status code is AP (Delivered with confirmation)
  • If the call fails with a 4XX error, the MLS status code is RE (Not delivered)
  • If the call fails with a 5XX error, ion-AP will try to deliver again a number of times. If the second attempt fails, ion-AP will try to deliver more times, but an MLS with status AB is sent. This is due to the Peppol requirement that an MLS is always returned within 20 minutes.

If there are only SEND_EMAIL triggers, or no triggers configured at all, the MLS response will always be AB (Delivered without confirmation).

Receiving MLS messages

When an MLS message is sent to ion-AP, it will match the send transaction that the MLS refers to. The MLS message is then coupled to that send transaction, and the transaction’s details page shows the MLS status and summary.

If an MLS arrives for an unknown transaction, or if the transaction already has an MLS stored, the new MLS is ignored.

As of yet, received MLS messages do not trigger and webhooks or callbacks.

Viewing MLS status

Web interface

MLS messages are exchanged over the Peppol network just like ‘main’ documents, and you can retrieve all details about a sent or received MLS just like you can for main documents. However, they do not show up in the Send Transactions and Receive Transactions overview directly. MLS messages are considered child transactions of the main document transaction.

This means that you can see the MLS status (sent or received) as part of the details of a send or receive transaction. You can click the ‘view transaction’ button to see the full MLS transaction details.

API

The API for transactions has been expanded with the following fields:

Send transactions have one new (optional, read-only) field mls_receive_transaction.

This new field is a nested data structure:

"mls_receive_transaction": {
    "id": 123,
    "received_on": "2026-08-24T14:15:22Z",
    "mls_response_code": "RE",
    "mls_response_description": "Failed to deliver",
    "mls_summary": "Errors: 1, warnings: 0. The remote system is unavailable.",
    "links": {
        "self": "https://test.ion-ap.net/api/v2/receive-transactions/123"
    }
}

This field is optional; if it is not set, it means no MLS has been received.

For receive transactions, there are three additional fields: mls_send_transaction, mls_not_sent_reason, and mls_not_sent_reason_text.

If an MLS is sent, a summary of the MLS and its transaction is provided in mls_send_transaction:

"mls_send_transaction": {

    "id": 456,
    "created_on": "2026-08-24T14:15:22Z",
    "sent_on": "2026-08-24T14:15:22Z",
    "state": "SENT",
    "mls_response_code": "AP",
    "mls_response_description": "Document delivered",
    "mls_summary": "",
    "links": {
        "self": "https://test.ion-ap.net/api/v2/send-transactions/456"
    }
}

If no MLS is sent, the other two fields are used; mls_not_sent_reason contains either the value MLS_RECIPIENT_NOT_FOUND, if the sending service provider’s MLS address could not be found on the network, or MLS_TYPE_FAILURE_ONLY, if the sender indicated it only wanted MLS messages on errors.

The field mls_not_sent_reason_text contains a textual description of this reason.