Skip to content

Getting Started

This quickstart gets you from “no setup” to a minimal working result: publish a message, fetch it, and acknowledge it.

Prerequisites

  • An Iron Messages account (sandbox is fine for this quickstart)
  • An API key with scopes:
  • messages:write (publish)
  • messages:read (consume)
  • Tools:
  • curl
  • jq (optional, but makes outputs easier to read)

Quickstart (end-to-end)

1) Set your API key and base URL

export IRON_API_KEY='YOUR_SANDBOX_KEY'
export IRON_BASE_URL='https://sandbox.api.iron.example'

2) Publish a “hello world” message

MESSAGE_ID=$(curl -sS -X POST "$IRON_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $IRON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-hello-1" \
  -d '{"type":"hello","data":{"name":"world"}}' | jq -r .id)

echo "published: $MESSAGE_ID"

Expected output (example):

{
  "id": "msg_01JFW1E5V3R9C2T4Z9G7X1K3P9",
  "status": "enqueued",
  "type": "hello",
  "created_at": "2025-12-20T13:10:50Z"
}

If you don’t have jq, run the curl command without the pipe and copy the id into MESSAGE_ID manually.

3) Poll for a message

curl -sS "$IRON_BASE_URL/v1/messages:poll?max=1&visibility_timeout_seconds=30" \
  -H "Authorization: Bearer $IRON_API_KEY"

Expected output (example):

{
  "messages": [
    {
      "id": "msg_01JFW1E5V3R9C2T4Z9G7X1K3P9",
      "type": "hello",
      "data": {"name": "world"},
      "delivery_attempt": 1
    }
  ]
}

4) Acknowledge the message

curl -sS -X POST "$IRON_BASE_URL/v1/messages/$MESSAGE_ID:ack" \
  -H "Authorization: Bearer $IRON_API_KEY"

Expected output:

{ "status": "acked" }

Next steps

Next: Getting Started · Reference · Changelog · Support