REST API

Base URLs:

• Sandbox: https://sandbox.api.iron.example
• Production: https://api.iron.example

All requests require:

• Authorization: Bearer <API_KEY>

Publish a message

POST /v1/messages

Headers:

• Content-Type: application/json
• Idempotency-Key: <string> (recommended)

Request body:

Field	Type	Required	Description
type	string	yes	Message type (e.g. email.send)
data	object	yes	JSON payload

Example:

curl -sS -X POST "$IRON_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $IRON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-1" \
  -d '{"type":"demo","data":{"n":1}}'

Response 200:

{ "id": "msg_...", "status": "enqueued", "type": "demo", "created_at": "..." }

Poll for messages

GET /v1/messages:poll

Query parameters:

Name	Type	Default	Description
max	int	1	Max messages returned (1–50)
visibility_timeout_seconds	int	30	Claim duration before redelivery

Response 200:

{ "messages": [{ "id": "msg_...", "type": "...", "data": {}, "delivery_attempt": 1 }] }

Acknowledge a message

POST /v1/messages/{id}:ack

Response 200:

{ "status": "acked" }

Status codes

Code	Meaning
200	Success
400	Invalid request
401	Unauthorized
403	Insufficient scope
404	Not found
409	Conflict (e.g. invalid state transition)
429	Rate limited
500	Internal error

---

Next: Getting Started · Reference · Changelog · Support