Quickstart

Create a queue, send a message, receive it with a long poll and acknowledge it, with curl or the ezgh CLI.

This quickstart creates a standard queue, sends a message to it, receives the message on the live host and acknowledges it, with curl and jq.

Before you start

An API key with QueuesFullAccess on the project (or the root user’s), in EZGH_API_KEY.
The organization’s and project’s IDs (UUIDs, on their pages in the console), in ORG_ID and PROJECT_ID.

export BASE="https://queues-api.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID"
export LIVE="https://queues-live.ezghcloud.com/v1/organizations/$ORG_ID/projects/$PROJECT_ID"

Sending goes to queues-api.ezghcloud.com; receiving and acknowledging go to queues-live.ezghcloud.com.

1. Create a queue

QUEUE_ID=$(curl -sS -X POST "$BASE/queues" \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "orders" }' | jq -r .id)

CreateQueue answers 201 with the queue. Every setting you leave out takes its default: a standard queue, a 30-second visibility timeout and 4 days’ retention.

{
  "id": "01999f3c-7a1e-7b2a-9c4d-5e6f7a8b9c0d",
  "slug": "que_4k2m9x0a7qpe",
  "resourceName": "ezgh:us-west-1:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:que_4k2m9x0a7qpe",
  "organizationId": "01995a10-3c2b-7d4e-9f01-2a3b4c5d6e7f",
  "projectId": "01995a12-8e7d-7c6b-a5f4-3e2d1c0b9a87",
  "name": "orders",
  "type": "standard",
  "visibilityTimeoutSeconds": 30,
  "retentionSeconds": 345600,
  "delaySeconds": 0,
  "receiveWaitSeconds": 0,
  "redrive": null,
  "contentBasedDedup": false,
  "partitions": 1,
  "counts": { "visible": 0, "inFlight": 0, "delayed": 0, "truncated": false },
  "tags": {},
  "createdAt": "2026-10-13T17:02:11Z",
  "updatedAt": "2026-10-13T17:02:11Z"
}

2. Send a message

curl -sS -X POST "$BASE/queues/$QUEUE_ID/messages" \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [ { "body": "{\"orderId\": \"o-123\"}", "attributes": { "source": "checkout" } } ] }'

{ "messages": [ { "messageId": "01999f3d-02b4-7c1d-8e2f-3a4b5c6d7e8f" } ] }

A body is text, up to 256 KiB with its attributes; this one is JSON. One SendMessages request sends 1 to 10 messages.

3. Receive it

curl -sS -X POST "$LIVE/queues/$QUEUE_ID/messages/receive" \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "maxMessages": 10, "waitSeconds": 20 }' | tee received.json

{
  "messages": [
    {
      "messageId": "01999f3d-02b4-7c1d-8e2f-3a4b5c6d7e8f",
      "receiptHandle": "AQAAAH8…",
      "body": "{\"orderId\": \"o-123\"}",
      "attributes": { "source": "checkout" },
      "sentAt": "2026-10-13T17:02:40Z",
      "firstReceivedAt": "2026-10-13T17:03:05Z",
      "receiveCount": 1
    }
  ]
}

ReceiveMessages waits up to waitSeconds for messages and answers as soon as it has some, or with an empty list when the wait ends. The message is now in flight: hidden from other consumers for the queue’s visibility timeout, 30 seconds. If it isn’t acknowledged by then, it’s delivered again.

4. Acknowledge it

curl -sS -X POST https://queues-live.ezghcloud.com/v1/receipts/ack \
  -H "Content-Type: application/json" \
  -d "{ \"receiptHandles\": [\"$(jq -r '.messages[0].receiptHandle' received.json)\"] }"

{ "results": [ { "ok": true } ] }

Acknowledging deletes the message. It takes no credential: the receipt handle allows it.

5. Clean up

curl -sS -X DELETE "$BASE/queues/$QUEUE_ID" -H "Authorization: Bearer $EZGH_API_KEY"

DeleteQueue answers 204 and deletes the queue’s messages.

With the CLI

The ezgh CLI (0.22.0 or later) does the same with the project’s queues named by name, and sends receives and acknowledgements to the live host for you:

ezgh queues create orders
ezgh queues send orders --body '{"orderId": 1042}'
ezgh queues receive orders --wait 20          # prints each message with its receipt handle
ezgh queues ack <receipt-handle>              # or: ezgh queues receive orders --ack
ezgh queues delete orders --yes

See ezgh queues for every command.

Write a consumer loop: Pull consumers.
Have Queues call your endpoint instead: Push subscriptions.
Send failed messages somewhere you can look at them: Dead-letter queues.