Message Queues

Pull-based message queues with HTTP long-polling. Producers enqueue via HTTP, consumers pull when ready. Like SQS, but simpler and EU-hosted.

How It Works

1. Create a queue with a name, visibility timeout, and max receives
2. Producers enqueue messages via the API — any JSON payload
3. Consumers receive messages via HTTP long-polling — messages are locked while being processed
4. Acknowledge to mark a message as done, or nack to return it to the queue
5. Messages that fail too many times move to dead letter automatically

Concepts

Visibility Timeout

When a consumer receives a message, it becomes invisible to other consumers for the visibility timeout period (default: 30 seconds). This prevents duplicate processing. If the consumer doesn't acknowledge within the timeout, the message becomes available again.

Receipt Handle

Each received message includes a receipt_handle — a one-time token used to acknowledge or reject the message. Receipt handles are only valid while the message is locked.

Dead Letter

Messages that are received but never acknowledged will keep returning to the queue. After being received max_receives times (default: 5), the message moves to the dead state. Dead messages can be inspected and retried from the dashboard or API.

Long-Polling

Consumers can set wait=20 on the receive endpoint to hold the connection open for up to 20 seconds. If a message arrives during the wait, it's returned immediately. This is more efficient than polling.

Quick Start

1. Create a queue

curl -X POST https://runlater.eu/api/v1/mq \
  -H "Authorization: Bearer pk_xxx.sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-events",
    "visibility_timeout_seconds": 30,
    "max_receives": 5
  }'

const res = await fetch("https://runlater.eu/api/v1/mq", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.RUNLATER_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "order-events",
    visibility_timeout_seconds: 30,
    max_receives: 5
  })
})

2. Enqueue a message

curl -X POST https://runlater.eu/api/v1/mq/mq_YOUR_SLUG/messages \
  -H "Authorization: Bearer pk_xxx.sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "event": "order.created",
      "data": { "id": 123, "total": 49.99 }
    }
  }'

await fetch(`https://runlater.eu/api/v1/mq/${slug}/messages`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    body: { event: "order.created", data: { id: 123 } }
  })
})

3. Receive messages (consumer)

# Long-poll: wait up to 20s for messages, receive up to 5
curl "https://runlater.eu/api/v1/mq/mq_YOUR_SLUG/receive?wait=20&max=5" \
  -H "Authorization: Bearer pk_xxx.sk_xxx"

// Consumer loop with long-polling
while (true) {
  const res = await fetch(
    `https://runlater.eu/api/v1/mq/${slug}/receive?wait=20&max=5`,
    { headers: { "Authorization": `Bearer ${apiKey}` } }
  )
  const { data: messages } = await res.json()

  for (const msg of messages) {
    try {
      await processMessage(msg.body)
      // Acknowledge on success
      await fetch(
        `https://runlater.eu/api/v1/mq/${slug}/ack/${msg.receipt_handle}`,
        { method: "DELETE", headers: { "Authorization": `Bearer ${apiKey}` } }
      )
    } catch (err) {
      // Nack to return to queue immediately
      await fetch(
        `https://runlater.eu/api/v1/mq/${slug}/nack/${msg.receipt_handle}`,
        { method: "POST", headers: { "Authorization": `Bearer ${apiKey}` } }
      )
    }
  }
}

API Reference

Interactive API docs with request/response schemas are available at /api/v1/docs (Swagger UI).

Queue Configuration

Message Lifecycle

available  --[receive]-->  locked  --[ack]-->  completed
                                |
                                |--[nack]--> available
                                |
                                |--[timeout expires]--> available
                                |
                                |--[max_receives hit]--> dead  --[retry]--> available

Receive Parameters

Message Management

Beyond the receive/ack/nack flow, you can manage individual messages and clean up queues programmatically.

Delete a message

Permanently removes a message from the queue, regardless of its status.

curl -X DELETE https://runlater.eu/api/v1/mq/order-events/messages/MSG_ID \
  -H "Authorization: Bearer pk_xxx.sk_xxx"
# Returns 204 No Content

Move to dead letter

Manually move an available or locked message to the dead letter state. Useful for messages you know are bad and don't want retried automatically. Returns 422 if the message is already completed or dead.

curl -X POST https://runlater.eu/api/v1/mq/order-events/messages/MSG_ID/dead-letter \
  -H "Authorization: Bearer pk_xxx.sk_xxx"
# Returns the message with status "dead"

Retry a dead-lettered message

Resets a dead-lettered message back to available with receive_count=0, giving it a fresh start. Returns 422 if the message is not in dead letter state.

curl -X POST https://runlater.eu/api/v1/mq/order-events/messages/MSG_ID/retry \
  -H "Authorization: Bearer pk_xxx.sk_xxx"
# Returns the message with status "available"

Purge completed messages

Deletes all completed messages from a queue in one call. Useful for cleaning up after batch processing.

curl -X DELETE https://runlater.eu/api/v1/mq/order-events/messages \
  -H "Authorization: Bearer pk_xxx.sk_xxx"
# Returns {"data": {"purged": 42}}

Billing

Each enqueued message counts as one execution toward your monthly limit. Receiving, acking, and nacking are free. Unlimited queues on all tiers.

Best Practices

• Always acknowledge — unacked messages return to the queue after the visibility timeout and eventually move to dead letter.
• Use long-polling — set wait=20 to minimize requests. The server responds immediately when messages arrive.
• Nack on failure — if processing fails, nack the message to make it immediately available for retry instead of waiting for the visibility timeout.
• Set visibility timeout > processing time — if processing takes 60 seconds, set the timeout to 90 or more.
• Batch enqueue — send up to 10 messages per request to reduce API calls.
• Batch ack — acknowledge multiple messages in one request after processing a batch.
• Monitor dead letters — check the dashboard or API for dead messages that need attention.