Receiving messages over HTTPS (pull)

Synura can hold messages for you to collect over HTTPS. Your system makes outbound calls to fetch whatever is queued, then acknowledges each message once you have stored it. There is nothing inbound to open and no firewall change to make. This is the mirror of sending: you already make an outbound call to send, and now you make an outbound call to receive.

When to use this

Use the pull API when your system can make outbound HTTPS calls but cannot accept inbound connections. This is the common case for a system that sits inside a hospital network.

If your system can accept an inbound HTTPS call from us, we can deliver straight to your endpoint instead. If you run an integration engine on HL7 over MLLP, use Synura Connect. Both are covered elsewhere in these docs.

Authentication

Every call uses your endpoint API key. Find it on the API Keys page in the Synura dashboard.

Send it in the Authorization header:

Authorization: Synura-Key YOUR_API_KEY

Your first call

Fetch a batch of queued messages:

curl -H "Authorization: Synura-Key YOUR_API_KEY" \
  https://api.synura.io/v1/delivery/messages

The response contains a batch of messages and a batch_id. If more messages are waiting, remaining is greater than zero and you can call again.

Pull, store, then acknowledge

Delivery is at least once. The rule that keeps it safe is simple. Acknowledge a message only after you have safely stored it.

1. Pull a batch. The messages are held for you and will not go to anyone else.
2. Store every message in the batch in your own system.
3. Acknowledge the batch. This tells Synura you have it and releases the next batch.

A successful fetch is not an acknowledgement. If you acknowledge before you have stored a message and your process then crashes, that message is gone. If you acknowledge only after the message is safely stored, a crash simply leaves it unacknowledged and Synura delivers it again on your next call. Store first. Acknowledge second.

Acknowledge a whole batch once you have stored all of it:

curl -X POST -H "Authorization: Synura-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"batch_id":"THE_BATCH_ID"}' \
  https://api.synura.io/v1/delivery/messages/ack

A reference poll loop

Copy this as your starting point. It fetches a batch, stores each message, then acknowledges the batch only after every message is safely written. Replace the storage step with your own durable write.

#!/usr/bin/env bash
set -euo pipefail

API_KEY="${SYNURA_API_KEY:?Set SYNURA_API_KEY}"
BASE_URL="https://api.synura.io"
AUTH="Authorization: Synura-Key ${API_KEY}"

while true; do
  resp="$(curl -fsS -H "$AUTH" "${BASE_URL}/v1/delivery/messages?limit=10")"
  batch_id="$(echo "$resp" | jq -r '.batch_id')"
  count="$(echo "$resp" | jq '.messages | length')"

  if [ "$count" -eq 0 ]; then
    sleep 5
    continue
  fi

  # Store every message FIRST. Replace this with your own durable write,
  # for example a database insert that has committed.
  echo "$resp" | jq -c '.messages[]' | while read -r msg; do
    id="$(echo "$msg" | jq -r '.id')"
    echo "$msg" | jq -r '.payload_b64' | base64 --decode > "./inbox/${id}"
    sync
  done

  # Acknowledge ONLY after every message above is safely stored.
  curl -fsS -X POST -H "$AUTH" -H "Content-Type: application/json" \
    -d "{\"batch_id\":\"${batch_id}\"}" \
    "${BASE_URL}/v1/delivery/messages/ack" > /dev/null
done

Need a hand

Contact support@synura.io with your subdomain and we will help you get set up.