# Get started with Queues

Create a queue with a dead-letter queue, send a message, receive and delete it, and delete both queues again, in about ten minutes.

Replace _my-queue_ with a name of your own, and _my-queue-dlq_ with that name followed by `-dlq`.

## Prerequisites

- Permission for `queue:ListQueues`, `queue:GetQueueAttributes`, `queue:CreateQueue`,
  `queue:SendMessage`, `queue:ReceiveMessage`, `queue:DeleteMessage` and `queue:DeleteQueue`.
- For the CLI steps, the dcloud CLI, signed in. For the API steps, an access key (see
  [Security](security.md)).

## Step 1: Create a queue

You create two queues: _my-queue_, and _my-queue-dlq_ as its dead-letter queue, which takes a
message after five receives without a delete. Requests and stored messages are billed from now on.

**Console**
1. Open **Queues**, then choose **Create queue**.
2. For **Name**, enter my-queue.
3. Leave **Dead-letter queue** selected, with 5 receives.
4. Choose **Create**.

The console creates _my-queue-dlq_ and then _my-queue_, and opens the queue's page.

**CLI**
```sh
dcloud queue queues create --name my-queue-dlq
dcloud queue queues create --name my-queue --dead-letter-queue '{"name":"my-queue-dlq","maxReceiveCount":5}'
```

**API**
```http
POST /queue/api/queues
{ "name": "my-queue-dlq" }
```

```http
POST /queue/api/queues
{ "name": "my-queue", "deadLetterQueue": { "name": "my-queue-dlq", "maxReceiveCount": 5 } }
```

## Step 2: Send a message

**Console**
1. On the queue's page, choose **Send and receive**.
2. Under **Send a message**, for **Body**, enter `{"orderId": 42}`.
3. Choose **Send**.

The section shows `Sent` and the new message's id.

**CLI**
```sh
dcloud queue messages send my-queue --body '{"orderId": 42}'
```

**API**
```http
POST /queue/api/queues/my-queue/messages
{ "body": "{\"orderId\": 42}" }
```

The answer is `201` with the message's `messageId`.

## Step 3: Receive and delete the message

A receive hides the message from other consumers for the visibility timeout (30 seconds on a new
queue). Delete it within that time, or it is delivered again.

**Console**
1. Under **Receive messages**, choose **Poll for messages**.
2. On the message, choose **Delete**.

The message disappears from the list.

**CLI**
```sh
dcloud queue messages receive my-queue --wait-seconds 20
dcloud queue messages delete my-queue receipt-handle
```

Replace _receipt-handle_ with the `receiptHandle` the receive printed.

**API**
```http
POST /queue/api/queues/my-queue/receive
{ "waitSeconds": 20 }
```

Then delete the message with the `receiptHandle` from the answer:

```http
DELETE /queue/api/queues/my-queue/messages/{receiptHandle}
```

## Clean up

Delete _my-queue_ first: a queue that another queue uses as its dead-letter queue cannot be
deleted.

**Console**
1. On _my-queue_'s page, choose **Danger zone**.
2. Under **Delete queue**, choose **Delete queue**, enter the queue's name, and choose
   **Delete queue**. The console returns to the queue list.
3. Open _my-queue-dlq_ and delete it the same way.

**CLI**
```sh
dcloud queue queues delete my-queue
dcloud queue queues delete my-queue-dlq
```

**API**
```http
DELETE /queue/api/queues/my-queue
```

```http
DELETE /queue/api/queues/my-queue-dlq
```

## Next steps

- [Message delivery](message-delivery.md)
- [Use an SQS client](use-an-sqs-client.md)
- [Receive and delete messages](receive-and-delete-messages.md)
