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. 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 monitors the message status until it reaches one of these states: delivered, failed, or parked.

1. A message is created through the POST /messages/create-business-transaction or any of the POST requests using the Transaction resource (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.
2. 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/:mid/documents call. The message status remains notset until all documents are added.
3. If all the documents have been added, this means that the more parameter in the last POST /messages/:mid/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.
4. If the processing and the delivery have been successful, the message status is set to delivered.
5. 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.
6. If the retrying attempts have been exhausted without success, the message status is set to failed. These messages can be retried or parked manually.
7. If the message's delivery is unsuccessful the status might be changed to 'pending review'. Messages with the 'pending review' status will be looked over and manually fixed if the input data is consistent.
8. 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.
9. 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 two 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.

When a receiver's back-end system monitors the pendingdelivery state, it does so through the GET /messages?status=pendingdelivery&transfer=inbound call.

1. 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/:mid/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.
2. If the message has been imported successfully, the message status changes to delivered using the POST /messages/:mid/mark-as-delivered call. Delivered messages can be retried.
3. 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.
4. 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 receiver's back-end system monitors the pendingprocessing state, it does so through the GET /messages?status=pendingprocessing&transfer=inbound call. After it has successfullyWhen a receiver's back-end system monitors processed the message, the message status can be updated using the POST /messages/:mid/mark-as-processed call. The message status is then changed to pendingdelivery and the message will then be waiting for the second system to handle it.

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

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