Guided Tour: Messaging Services

For more details, check our online documentation: MAPI Messaging API Reference

Sending electronic documents

1. Create a random unique identifier (GUID) and store internally. This will become the message identifier (:mid), passed as the messageId parameter when you submit the document.
2. Prepare the XML message and submit the business documents using:
   • POST /messages/create-business-transaction
     Send the XML file as the raw request body with Content-Type: application/octet-stream (see Uploading the document).
     To define the type of document being submitted, ensure the parameter transactionGroupIdentifier is set, e.g. SubmitInvoice or CorrectWithCredit.
     When including additional attachments in the message, ensure the parameter more is set to true. Otherwise set it to false to trigger processing and delivery of the message.
3. Optionally, stream a binary payload as attachment (e.g. timesheet, product description) using:
   • POST /messages/:mid/documents
     Send the file as the raw request body with Content-Type: application/octet-stream. The contentType query parameter is the file's own MIME type; supported are images, PDF, XLSX, CSV and plain text files. Set more to true or false depending on if processing can be triggered or not. If desired, set embedDocument to true.
4. Follow the state of the message through webhooks: Unimaze sends a messageStatusChanged event each time the delivery status changes. The states delivered (delivered to the receiver), failed (there was an error) and parked (manually parked as handled) are final states.
   To check the state at any time, for example if you may have missed an event, use:
   • GET /messages/:mid/status
     This gives both delivery information and message handling traces.
5. Store the referenceId parameter for each document for later displaying the document(s), see Receiving electronic documents below.

Getting notified of incoming documents

To keep incoming documents from piling up in the inbox, set up a webhook endpoint for inbound messages. When a message is ready to be fetched, Unimaze sends your endpoint a deliveryNotified event. Fetch the documents into the ERP system as described below.

Once a day, also run a safety-net check with GET /messages?status=pendingdelivery&transfer=inbound, and handle any message that is still pending in the same way.

Fetching pending messages on a schedule instead (polling) is the legacy approach, supported for existing integrations. See Polling (legacy).

Receiving electronic documents

1. When a deliveryNotified event arrives, read the message from it: messageId is the unique identifier (GUID), and data is the message envelope, with the action parameter and the referenceId of each document.
2. If validationStatus of a message is not approved, it has one or more validation errors. Either mark the message as delivered or parked so that it will be removed from the list of pending incoming messages. If you like to fetch validation errors or warnings use:
   • GET /messages/:mid/validations
3. Get the business document in raw XML format using:
   • GET /messages/:mid/documents/core
     Optionally, get any attached documents and store them if needed:
   • GET /messages/:mid/documents/{nameOrIndex}
4. Change the state of the message to delivered using:
   • POST /messages/:mid/mark-as-delivered
     Generally, marking the message delivered should be done as soon as possible (within minutes or hours).
5. To allow a user to view the document or any of the attached documents, use:
   • GET /messages/display/:referenceId (optionally add the ?lang=<language> parameter)