Message flow

A message goes through several states during message processing and delivery and the message status changes accordingly.
Some states occur as a result of internal message processing and others as a result of an API call.
In certain cases, such as when a message is parked or retried, users need to make the changes manually through the UI.

The same message can have different statuses in the sender's outbox and the receiver's inbox.
In both cases, the message status is tracked until it is updated to delivered, failed, or parked.
Each status change is announced with a messageStatusChanged webhook event, so your systems don't need to check the status repeatedly.
These states are considered final because typically no further state changes will occur.

Outbound messages

The following diagram shows the states that the message undergoes from the sender's perspective.

After the message is pushed to the messaging server, the sender's back-end system follows the message status through messageStatusChanged events until it reaches one of these states: delivered, failed, or parked.
To check the status at any time, use GET /messages/{messageId}.

A message is created through the POST /messages/create-business-transaction or any of the POST /transactions/... calls (see Creating messages).
The message processing and delivery follow the same steps regardless of the call that was used to create the message.
Whether any attachments can be submitted to the message is managed through the more parameter.
This is a required query parameter used when creating messages and when adding documents.
If the more parameter is set to true, the message is open and other documents can be added.
Setting the value to false closes the message and prevents you from adding attachments.
If an additional document needs to be attached to the message, the message status is set to notset.
The sender can add new documents to the message if the more parameter has been set to true in the call that was used to create the message.
An attachment is uploaded using the POST /messages/{messageId}/documents call.
The message status remains notset until all documents are added.
If all the documents have been added, this means that the more parameter in the last POST /messages/{messageId}/documents request made has been set to false.
The message status is set to received and the message is ready for processing.
If there were no additional documents, the message status is set directly to received.
If the processing and the delivery have been successful, the message status is set to delivered.
If the message processing and delivery have been unsuccessful, the message status is changed to retrying.
This typically occurs due to external failures, such as network issues.
Messages are retried until one of the retrying attempts is successful or until the maximum number of attempts is reached.
If the processing and the delivery have been successful, the message status is set to delivered.
If the retrying attempts have been exhausted without success, the message status is set to failed.
These messages can be retried or parked manually.
In rare cases a failed delivery needs manual handling before the final state is set, and the message is held as pendingfailure.
It then becomes failed, which is final, or delivered if a retry succeeds.
Parking a message indicates that the message is not going to be delivered through the messaging server.
A message can be parked from the UI if its status is failed.
Parking a message might also mean that it has been delivered in another way.
The user provides a reason for parking the message, which facilitates message tracking.
Parked messages can also be retried.
Retrying a message is done from the UI when the message delivery has been unsuccessful.
This changes the message status to received and triggers the delivery process again.
The sender can retry a message if its message status is failed, parked, or delivered.

Inbound messages

See how messages are handled after they reach the receiver's inbox in the following diagram.
The message status is used for tracking the message progress until it is set to delivered, failed, or parked, which are considered final states.

When a message reaches the receiver's back-end system, the message status is set to one of these statuses depending on the party setup:

pendingdelivery: This is the default configuration where an accounting system imports documents directly.
pendingprocessing: This is used in special cases when another back-end system monitors and controls the flow of documents, for example, an invoice acceptance system, before giving control to a second system, which is typically an accounting system.

Some setups also have a pre-processing step, with the statuses pendingpreprocessing and preprocessing, before pendingprocessing or pendingdelivery. Your systems don't act on it.

See Processing step for the events.

When a message becomes pendingdelivery, the receiver's back-end system gets a deliveryNotified webhook event, fetches the documents and confirms the outcome, as described in Receiving inbound messages.
A daily safety-net check with GET /messages?status=pendingdelivery&transfer=inbound finds any message that was never confirmed. Checking this list on a schedule instead (polling) is the legacy approach, see Polling (legacy).

If the receiver's back-end system could not import the message, the message status must be set to failed, which is achieved through the POST /messages/{messageId}/mark-as-failed call.
Failed messages can be parked or retried.
For example, this might happen when the import implementation does not support a payment means and must be updated.
If the message has been imported successfully, the message status changes to delivered using the POST /messages/{messageId}/mark-as-delivered call.
Delivered messages can be retried.
When there are issues during message processing or delivery, the message can be parked.
Messages can be parked if their status is pendingdelivery, pendingprocessing, delivered, or failed. This can be done only from the UI.
If a message has been parked, this indicates that the document has been delivered in another message or in some other way or that the issues encountered have been solved.
The message delivery can be triggered again if the message status is delivered, failed, or parked.
To retry a message, you need to use the UI.
When the delivery is retried, the message status is set again to received.
For more information about the message flow from the sender's point of view, see Outbound messages.

When a message becomes pendingprocessing, the receiver's processing system gets a processingNotified webhook event. A daily safety-net check with GET /messages?status=pendingprocessing&transfer=inbound finds any message it never processed.
While it works on the message, the processing system can set the status to processing with the POST /messages/{messageId}/mark-as-in-process call, if the participant is set up for it.
After it has successfully processed the message, the message status can be updated using the POST /messages/{messageId}/mark-as-processed call.
The message status is then changed to pendingdelivery, and the second system gets a deliveryNotified event to handle it.

Alternatively, the system can prevent the second system from processing it by setting it to delivered using the POST /messages/{messageId}/mark-as-delivered call.

Messages in the pendingprocessing or pendingdelivery state can be parked through the UI.