Polling (legacy)

With polling, your back-end calls MAPI on a schedule to check whether new inbound messages are waiting to be imported, and what has happened to the messages it sent.

sequenceDiagram
    participant E as Your back-end (ERP)
    participant U as Unimaze

    loop Every 10–30 minutes
        E->>U: GET /messages?status=pendingdelivery&transfer=inbound
        U-->>E: List of pending messages
        E->>U: GET /transactions/submit-invoice?messageId=:mid
        U-->>E: Document data (JSON)
        E->>U: POST /messages/:mid/mark-as-delivered
    end

How it works

Inbound messages

1. Call GET /messages?status=pendingdelivery&transfer=inbound to list pending inbound messages. Page through the results with offset and limit (default 50).
2. For each message, fetch the document data based on its action.
3. Import the document into your back-end.
4. Call POST /messages/:mid/mark-as-delivered or POST /messages/:mid/mark-as-failed so the message no longer appears in the pending list.

The full steps are described in Receiving inbound messages.

Outbound messages

For each message you have sent that has not reached a final state yet, call GET /messages/:mid/status and update the document in your back-end. Stop checking a message when it reaches a final state: delivered or failed (or parked, if handled manually in MUI). pendingfailure is not final: in rare cases manual handling delays the final state, and the message then becomes failed or delivered.

Recommendations

• Poll every 10–30 minutes. More frequent polling adds load without much benefit. If you need faster reactions, use webhooks.
• Always mark messages as delivered or failed. Otherwise they are returned by every poll.
• Show pending counts to users. Use GET /parties/{isoIdentifier}/pending-summaries to show a badge or alert in your application. It returns the number of documents in each pending status, with a localized subject and a link to those documents in Unimaze. transfer gives the direction of each status: incoming for received documents waiting for your system, outgoing for documents you sent that wait for review or booking. To show, for example, only billing documents waiting for your system, filter by action with the actions query parameter and use the statuses where transfer is incoming: GET /parties/{isoIdentifier}/pending-summaries?actions=SubmitInvoice,CorrectWithCredit,SubmitBillingResponse.

Moving from polling to webhooks

Webhooks trigger the same logic you already have, so the move is small. Move both directions, so you stop polling for inbound messages and for outbound status:

1. Expose an HTTPS endpoint, add it as a webhook endpoint and route both Inbound messages and Outbound messages to it (see Setting up webhooks). The first endpoint you add receives all categories automatically.
2. Inbound: when a deliveryNotified event arrives, verify the signature and run your existing fetch-import-mark steps for that one message, using messageId from the body.
3. Outbound: when a messageStatusChanged event arrives, update the document in your back-end from newValue (for example delivered or failed) instead of calling GET /messages/:mid/status. Tax reporting and lifecycle changes arrive the same way (taxReportingStatusChanged, lifecycleStatusChanged).
4. If you use pending import messages (GET /messages/pending-import), handle importNotified the same way as inbound messages and acknowledge with mark-as-imported (see Pending import messages).
5. Keep a polling job, but reduce it to a low frequency (for example daily) as a safety net: pending inbound messages that were notified but never acknowledged (see Unacknowledged messages), and outbound messages still without a final status.