---
title: "Quickstart"
description: "Create a queue, send a message, receive it with a long poll and acknowledge it, with curl or the ezgh CLI."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

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](/iam/api-keys)** 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`.

```sh
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

```sh
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](/queues-api/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.

```json
{
  "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

```sh
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" } } ] }'
```

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

A body is text, up to 256 KiB with its attributes; this one is JSON. One
[SendMessages](/queues-api/SendMessages/) request sends 1 to 10 messages.

## 3. Receive it

```sh
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
```

```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](/queues-api/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

```sh
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)\"] }"
```

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

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

## 5. Clean up

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

[DeleteQueue](/queues-api/DeleteQueue/) answers `204` and deletes the queue's messages.

## With the CLI

The [`ezgh` CLI](/cli/install) (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:

```sh
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`](/cli/reference/queues) for every command.

## Next

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

Source: https://docs.ezghcloud.com/queues/quickstart/index.mdx