Inbox / Outbox versions

Inbox/Outbox versions

Inbox submits messages for Link processing. Outbox retrieves outgoing transmissions selected by a configured transport type. For new integrations, use v3 when it is installed; its existing Inbox/Outbox v3 guide describes the token, reservation, download, and confirmation operations.

.NET clients

For .NET clients, we recommend using the Bizbrains.Link.Api.Proxy NuGet package. See .NET client library for the public NuGet feed, supported APIs, and shared guidance.

Choose a version

Area

v1

v2

v3

Inbox

JSON metadata and base64 file

Uses the same Inbox controller/route as v1 in this implementation

Metadata token followed by a raw-body upload

Outbox retrieval

JSON result per document; batched outgoing documents unsupported

JSON result per outgoing interchange; supports batching

Reserve metadata, then download each payload as raw bytes

Confirmation identifiers

Document IDs in the request body

Outgoing interchange IDs in the request body

Outgoing interchange ID in the URL

Outbox routes

/api/transport/outbox/...

/api/transport/outbox/v2/...

/api/transport/outbox/v3/...

Failure/redelivery operations

No dedicated routes in this controller

confirm-failed, mark-for-redelivery

Individual interchange failure/redelivery routes

The older Inbox route is /api/transport/inbox; selecting the v2 Swagger definition does not create /inbox/v2 in this implementation. Check the actual path in your environment's definition.

V1/v2 embed file bytes as base64 in JSON, with serialization and memory overhead. The checked legacy Outbox implementation rejects files larger than 125,000,000 bytes and marks their records as failed rather than returning the file. V3 separates payload transfer from metadata and avoids that base64 JSON representation. Host and gateway limits still apply.

Access and configuration

  • Inbox requires API_Transport_SendInterchange.

  • Outbox requires API_Transport_GetFromOutbox.

  • Both are included in API Transport.

  • Sending or retrieving for other partners requires the applicable additional permission: AllowSendFromMultiplePartners or AllowGetFromMultiplePartners.

A partner-linked service user should normally leave explicit sender/receiver selection empty to use its linked partner. Cross-partner selection and defaults differ by version: do not copy wildcard selectors or omitted-partner behavior between versions. In legacy Outbox, explicitly selecting a partner requires the multiple-partner permission; without a selection the user's linked partner is normally used. Use the v3 guide for its receiver and sender filters.

Configure the receiving Link flow for Inbox, and the outbound transport location/distribution for Outbox. transportTypeName is the configured Link transport type to select, not an instruction to perform that protocol in the API client. The receiving client processes the downloaded payload itself.

Legacy Outbox behavior

For v1, call get-files, persist the file, then confirm receipt and delivery using documentIds. V1 rejects an outbox item containing a batched outgoing interchange.

For v2, use interchangeIds; confirmation applies to the documents in those outgoing interchanges. Do not pass document IDs copied from a v1 implementation.

The legacy get-files operation normally removes the selected items from the outbox while retrieving them, before the client acknowledges receipt. V1's doNotUpdateStatus: true and v2's keepInOutbox: true retain them instead. Retention allows repeated retrieval; it is not a v3-style timed reservation. A client timeout after normal retrieval can therefore leave no item available to download again.

confirm-received records retrieval. confirm-delivered records completion and removes any retained outbox entry. V2's confirm-failed records failure and removes it; mark-for-redelivery returns the interchange to the queue.

Example: existing v2 client

Assume PartnerOutbox is a configured transport type and the service user is linked to the receiver. This example retrieves one file without retaining its outbox entry, saves the response and decoded payload, then confirms receipt:

Bash
set -euo pipefail
LINK_API_BASE='https://<your-link-api-host>'
LINK_PAT='<your-personal-access-token>'

curl --silent --show-error --fail-with-body \
  --user ":${LINK_PAT}" --header 'Content-Type: application/json' \
  --data '{"transportTypeName":"PartnerOutbox","maxNumberOfFiles":1,"keepInOutbox":false}' \
  "${LINK_API_BASE}/api/transport/outbox/v2/get-files" \
  --output outbox-response.json

# For a polling loop, an empty array means there is no work this time.
INTERCHANGE_ID=$(jq -er '.[0].interchange.entityId' outbox-response.json)
jq -r '.[0].interchangeOutFile.base64FileData' outbox-response.json \
  | base64 --decode > outgoing-payload.dat

jq -n --argjson id "${INTERCHANGE_ID}" \
  '{interchangeIds:[$id]}' > outbox-confirm.json

curl --silent --show-error --fail-with-body --include \
  --user ":${LINK_PAT}" --header 'Content-Type: application/json' \
  --data-binary '@outbox-confirm.json' \
  "${LINK_API_BASE}/api/transport/outbox/v2/confirm-received"

After the receiving application has successfully processed its saved payload, send the same confirmation file to /api/transport/outbox/v2/confirm-delivered. Both confirmations return 200 with an empty body. Use a durable storage mechanism in the real application and retain the interchange ID alongside the payload so processing can resume after a crash.

Migrate to v3

  1. Confirm v3 availability and configure it in the target environment. Its public guide states availability after Link 3.0.9741.18968; use the installed routes as the final check.

  2. For Inbox, replace the combined JSON/base64 submission with metadata token creation and a separate raw-payload submission. The configuration token is not the authentication token.

  3. For Outbox, replace get-files with reserve → download → persist → confirm-received → confirm-delivered/failed, using each returned interchangeId in its route.

  4. Replace array-based confirmation bodies with individual interchange routes and any agreed technical-status body. Do not confirm receipt before durable persistence: v3 receipt confirmation removes the item from the queue.

  5. Handle expired reservations by reserving again, and make processing tolerant of redelivery. Coordinate the switchover with existing pollers so old and new clients do not compete for the same work.

The full v3 request and response examples remain in the existing v3 guide; this page adds version choice and migration rather than duplicating it.