Amazon SQS via SDK: Your First Queue

Q: Why use long polling?

Long polling (WaitTimeSeconds up to 20) waits for a message instead of returning empty immediately. It cuts wasted requests and cost and reduces latency when messages arrive.

Q: Processing takes longer than the timeout - what do I do?

Either set a longer VisibilityTimeout on the queue, or call ChangeMessageVisibility to extend the timeout for that message while you keep working, so it is not redelivered.

Q: Can I receive more than one message at a time?

Yes. Set MaxNumberOfMessages up to 10 on ReceiveMessage to batch receives, and use DeleteMessageBatch to delete them together for fewer requests.

Amazon SQS is a managed message queue that buffers work between a producer and a worker.

This page runs the full loop from code: create a queue, send a message, receive it, then delete it once processed. It is the pull half of AWS messaging - SNS is the push half.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
 
sqs = boto3.client("sqs", region_name="us-east-1")
url = sqs.get_queue_url(QueueName="jobs")["QueueUrl"]
sqs.send_message(QueueUrl=url, MessageBody="job-1")
msgs = sqs.receive_message(QueueUrl=url, WaitTimeSeconds=10).get("Messages", [])
print([m["Body"] for m in msgs])

// --- TypeScript (AWS SDK v3) ---
import { SQSClient, GetQueueUrlCommand, SendMessageCommand, ReceiveMessageCommand } from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({ region: "us-east-1" });
const { QueueUrl } = await sqs.send(new GetQueueUrlCommand({ QueueName: "jobs" }));
await sqs.send(new SendMessageCommand({ QueueUrl, MessageBody: "job-1" }));
const { Messages } = await sqs.send(new ReceiveMessageCommand({ QueueUrl, WaitTimeSeconds: 10 }));
console.log((Messages ?? []).map((m) => m.Body));

When to reach for this:

Decoupling a fast API from slow background work.
Smoothing traffic spikes so workers process at a steady rate.
Retrying failed work safely without losing messages.
Distributing tasks across a pool of workers.

Working Example

Create a queue, send a message, receive it with long polling, process it, then delete it with its receipt handle - and clean up the queue.

# --- Python (boto3) ---
import boto3
 
sqs = boto3.client("sqs", region_name="us-east-1")
 
# 1. Create the queue (idempotent for the same name/attributes).
url = sqs.create_queue(
    QueueName="jobs",
    Attributes={"VisibilityTimeout": "30"},
)["QueueUrl"]
 
# 2. Send a message.
sqs.send_message(QueueUrl=url, MessageBody="job-1")
 
# 3. Receive with long polling (up to 10 messages, wait up to 20s).
resp = sqs.receive_message(
    QueueUrl=url, MaxNumberOfMessages=10, WaitTimeSeconds=20)
 
for m in resp.get("Messages", []):
    print("processing", m["Body"])
    # 4. Delete only AFTER successful processing, using the receipt handle.
    sqs.delete_message(QueueUrl=url, ReceiptHandle=m["ReceiptHandle"])
 
# 5. Clean up.
sqs.delete_queue(QueueUrl=url)

// --- TypeScript (AWS SDK v3) ---
import {
  SQSClient, CreateQueueCommand, SendMessageCommand,
  ReceiveMessageCommand, DeleteMessageCommand, DeleteQueueCommand,
} from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({ region: "us-east-1" });
 
// 1. Create the queue (idempotent for the same name/attributes).
const { QueueUrl } = await sqs.send(new CreateQueueCommand({
  QueueName: "jobs",
  Attributes: { VisibilityTimeout: "30" },
}));
 
// 2. Send a message.
await sqs.send(new SendMessageCommand({ QueueUrl, MessageBody: "job-1" }));
 
// 3. Receive with long polling (up to 10 messages, wait up to 20s).
const resp = await sqs.send(new ReceiveMessageCommand({
  QueueUrl, MaxNumberOfMessages: 10, WaitTimeSeconds: 20,
}));
 
for (const m of resp.Messages ?? []) {
  console.log("processing", m.Body);
  // 4. Delete only AFTER successful processing, using the receipt handle.
  await sqs.send(new DeleteMessageCommand({ QueueUrl, ReceiptHandle: m.ReceiptHandle }));
}
 
// 5. Clean up.
await sqs.send(new DeleteQueueCommand({ QueueUrl }));

What this demonstrates:

Receiving a message does not remove it; you must delete it after processing.
The ReceiptHandle from a receive - not the message id - is what DeleteMessage needs.
Long polling (WaitTimeSeconds) waits for messages instead of returning empty immediately.
The visibility timeout hides an in-flight message from other consumers while you work.

Deep Dive

The Receive-Delete Contract

ReceiveMessage returns a copy of the message and starts its visibility timeout. During that window the message is hidden from other consumers.
If you delete it before the timeout expires, it is gone for good.
If you do not delete it (your worker crashed, say), the timeout expires and the message becomes visible again for another attempt.
This is what makes SQS reliable: a message is not lost just because a worker failed mid-processing.
The receipt handle is a per-receive token; a new receive of the same message yields a new handle, and only the latest one deletes it.

Long Polling vs Short Polling

Short polling (the default when WaitTimeSeconds is 0) returns immediately, often empty, and bills a request each time.

# --- Python (boto3) ---
# Long polling: wait up to 20s for a message before returning.
resp = sqs.receive_message(QueueUrl=url, WaitTimeSeconds=20)

// --- TypeScript (AWS SDK v3) ---
// Long polling: wait up to 20s for a message before returning.
const resp = await sqs.send(new ReceiveMessageCommand({ QueueUrl, WaitTimeSeconds: 20 }));

Long polling cuts empty responses and cost, and lowers latency when a message does arrive. Prefer it almost always.

A message that repeatedly fails processing can loop forever. Attach a dead-letter queue via a redrive policy so that after a set number of receives, the poison message is moved aside for inspection instead of retrying endlessly.

Gotchas

Forgetting to delete - a received but undeleted message reappears after the visibility timeout and is processed again. Fix: call DeleteMessage with the receipt handle after successful processing.
Deleting with the wrong token - DeleteMessage needs the ReceiptHandle, not the MessageId. Fix: pass the receipt handle from the receive response.
Short polling by default - WaitTimeSeconds=0 returns many empty responses and wastes requests. Fix: set WaitTimeSeconds (up to 20) to enable long polling.
Visibility timeout too short - if processing outlasts the timeout, the message becomes visible and is processed twice. Fix: set the timeout above your worst-case processing time, or extend it with ChangeMessageVisibility.
Assuming exactly-once on standard queues - standard queues are at-least-once and can deliver duplicates. Fix: make processing idempotent, or use a FIFO queue for exactly-once.
No dead-letter queue - poison messages retry forever and block throughput. Fix: configure a redrive policy to a dead-letter queue.

Alternatives

Alternative	Use When	Don't Use When
SQS standard (this page)	High-throughput buffered work, order not critical	You need strict ordering or exactly-once
SQS FIFO	Strict ordering and exactly-once processing	You need maximum throughput over ordering
SNS	Push fan-out to many subscribers	One worker should pull each message
SNS + SQS fan-out	Many durable consumers of one event	A single simple queue suffices
EventBridge	Rich routing and many AWS event sources	Simple point-to-point work queues

FAQs

Does receiving a message remove it from the queue?

No. Receiving returns a copy and hides it via the visibility timeout. The message stays in the queue until you explicitly delete it with its receipt handle.

What is the receipt handle?

A token returned by a specific receive that identifies your hold on that message. DeleteMessage and ChangeMessageVisibility use it - not the message id, which is stable across receives.

What does the visibility timeout do?

It hides an in-flight message from other consumers while you process it. If you delete it in time, it is gone; if you crash, it reappears after the timeout for another attempt.

Why use long polling?

Long polling (WaitTimeSeconds up to 20) waits for a message instead of returning empty immediately. It cuts wasted requests and cost and reduces latency when messages arrive.

What happens if my worker crashes mid-processing?

The message is not deleted, so once its visibility timeout expires it becomes visible again and another consumer can process it. This is why SQS is reliable under worker failure.

Can I get duplicate messages?

On standard queues, yes - delivery is at-least-once, so duplicates are possible. Make your processing idempotent, or use a FIFO queue for exactly-once processing.

What is a dead-letter queue?

A separate queue that receives messages which failed processing a configured number of times. It stops poison messages from retrying forever and lets you inspect them.

How is SQS different from SNS?

SQS is pull: a worker receives and processes messages one group at a time. SNS is push: it delivers a copy to every subscriber. They are often combined in the fan-out pattern.

Processing takes longer than the timeout - what do I do?

Either set a longer VisibilityTimeout on the queue, or call ChangeMessageVisibility to extend the timeout for that message while you keep working, so it is not redelivered.

Can I receive more than one message at a time?

Yes. Set MaxNumberOfMessages up to 10 on ReceiveMessage to batch receives, and use DeleteMessageBatch to delete them together for fewer requests.

Amazon SNS via SDK: Your First Topic - the push half, and the fan-out source for queues.
AWS Lambda via SDK: Your First Function - a common queue consumer via event source mapping.
Core Services Basics - the one-call tour across all ten services.
Core AWS Services Best Practices - messaging defaults.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

This page runs the full loop from code: create a queue, send a message, receive it, then delete it once processed. It is the pull half of AWS messaging - SNS is the push half.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import boto3
 
sqs = boto3.client("sqs", region_name="us-east-1")
url = sqs.get_queue_url(QueueName="jobs")["QueueUrl"]
sqs.send_message(QueueUrl=url, MessageBody="job-1")
msgs = sqs.receive_message(QueueUrl=url, WaitTimeSeconds=10).get("Messages", [])
print([m["Body"] for m in msgs])

// --- TypeScript (AWS SDK v3) ---
import { SQSClient, GetQueueUrlCommand, SendMessageCommand, ReceiveMessageCommand } from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({ region: "us-east-1" });
const { QueueUrl } = await sqs.send(new GetQueueUrlCommand({ QueueName: "jobs" }));
await sqs.send(new SendMessageCommand({ QueueUrl, MessageBody: "job-1" }));
const { Messages } = await sqs.send(new ReceiveMessageCommand({ QueueUrl, WaitTimeSeconds: 10 }));
console.log((Messages ?? []).map((m) => m.Body));

When to reach for this:

Decoupling a fast API from slow background work.
Smoothing traffic spikes so workers process at a steady rate.
Retrying failed work safely without losing messages.
Distributing tasks across a pool of workers.

Working Example

Create a queue, send a message, receive it with long polling, process it, then delete it with its receipt handle - and clean up the queue.

# --- Python (boto3) ---
import boto3
 
sqs = boto3.client("sqs", region_name="us-east-1")
 
# 1. Create the queue (idempotent for the same name/attributes).
url = sqs.create_queue(
    QueueName="jobs",
    Attributes={"VisibilityTimeout": "30"},
)["QueueUrl"]
 
# 2. Send a message.
sqs.send_message(QueueUrl=url, MessageBody="job-1")
 
# 3. Receive with long polling (up to 10 messages, wait up to 20s).
resp = sqs.receive_message(
    QueueUrl=url, MaxNumberOfMessages=10, WaitTimeSeconds=20)
 
for m in resp.get("Messages", []):
    print("processing", m["Body"])
    # 4. Delete only AFTER successful processing, using the receipt handle.
    sqs.delete_message(QueueUrl=url, ReceiptHandle=m["ReceiptHandle"])
 
# 5. Clean up.
sqs.delete_queue(QueueUrl=url)

// --- TypeScript (AWS SDK v3) ---
import {
  SQSClient, CreateQueueCommand, SendMessageCommand,
  ReceiveMessageCommand, DeleteMessageCommand, DeleteQueueCommand,
} from "@aws-sdk/client-sqs";
 
const sqs = new SQSClient({ region: "us-east-1" });
 
// 1. Create the queue (idempotent for the same name/attributes).
const { QueueUrl } = await sqs.send(new CreateQueueCommand({
  QueueName: "jobs",
  Attributes: { VisibilityTimeout: "30" },
}));
 
// 2. Send a message.
await sqs.send(new SendMessageCommand({ QueueUrl, MessageBody: "job-1" }));
 
// 3. Receive with long polling (up to 10 messages, wait up to 20s).
const resp = await sqs.send(new ReceiveMessageCommand({
  QueueUrl, MaxNumberOfMessages: 10, WaitTimeSeconds: 20,
}));
 
for (const m of resp.Messages ?? []) {
  console.log("processing", m.Body);
  // 4. Delete only AFTER successful processing, using the receipt handle.
  await sqs.send(new DeleteMessageCommand({ QueueUrl, ReceiptHandle: m.ReceiptHandle }));
}
 
// 5. Clean up.
await sqs.send(new DeleteQueueCommand({ QueueUrl }));

What this demonstrates:

Receiving a message does not remove it; you must delete it after processing.
The ReceiptHandle from a receive - not the message id - is what DeleteMessage needs.
Long polling (WaitTimeSeconds) waits for messages instead of returning empty immediately.
The visibility timeout hides an in-flight message from other consumers while you work.

Deep Dive

The Receive-Delete Contract

ReceiveMessage returns a copy of the message and starts its visibility timeout. During that window the message is hidden from other consumers.
If you delete it before the timeout expires, it is gone for good.
If you do not delete it (your worker crashed, say), the timeout expires and the message becomes visible again for another attempt.
This is what makes SQS reliable: a message is not lost just because a worker failed mid-processing.
The receipt handle is a per-receive token; a new receive of the same message yields a new handle, and only the latest one deletes it.

Long Polling vs Short Polling

Short polling (the default when WaitTimeSeconds is 0) returns immediately, often empty, and bills a request each time.

# --- Python (boto3) ---
# Long polling: wait up to 20s for a message before returning.
resp = sqs.receive_message(QueueUrl=url, WaitTimeSeconds=20)

// --- TypeScript (AWS SDK v3) ---
// Long polling: wait up to 20s for a message before returning.
const resp = await sqs.send(new ReceiveMessageCommand({ QueueUrl, WaitTimeSeconds: 20 }));

Long polling cuts empty responses and cost, and lowers latency when a message does arrive. Prefer it almost always.

Dead-Letter Queues

Gotchas

Forgetting to delete - a received but undeleted message reappears after the visibility timeout and is processed again. Fix: call DeleteMessage with the receipt handle after successful processing.
Deleting with the wrong token - DeleteMessage needs the ReceiptHandle, not the MessageId. Fix: pass the receipt handle from the receive response.
Short polling by default - WaitTimeSeconds=0 returns many empty responses and wastes requests. Fix: set WaitTimeSeconds (up to 20) to enable long polling.
Visibility timeout too short - if processing outlasts the timeout, the message becomes visible and is processed twice. Fix: set the timeout above your worst-case processing time, or extend it with ChangeMessageVisibility.
Assuming exactly-once on standard queues - standard queues are at-least-once and can deliver duplicates. Fix: make processing idempotent, or use a FIFO queue for exactly-once.
No dead-letter queue - poison messages retry forever and block throughput. Fix: configure a redrive policy to a dead-letter queue.

Alternatives

Alternative	Use When	Don't Use When
SQS standard (this page)	High-throughput buffered work, order not critical	You need strict ordering or exactly-once
SQS FIFO	Strict ordering and exactly-once processing	You need maximum throughput over ordering
SNS	Push fan-out to many subscribers	One worker should pull each message
SNS + SQS fan-out	Many durable consumers of one event	A single simple queue suffices
EventBridge	Rich routing and many AWS event sources	Simple point-to-point work queues

FAQs

Does receiving a message remove it from the queue?

No. Receiving returns a copy and hides it via the visibility timeout. The message stays in the queue until you explicitly delete it with its receipt handle.

What is the receipt handle?

A token returned by a specific receive that identifies your hold on that message. DeleteMessage and ChangeMessageVisibility use it - not the message id, which is stable across receives.

What does the visibility timeout do?

It hides an in-flight message from other consumers while you process it. If you delete it in time, it is gone; if you crash, it reappears after the timeout for another attempt.

Why use long polling?

Long polling (WaitTimeSeconds up to 20) waits for a message instead of returning empty immediately. It cuts wasted requests and cost and reduces latency when messages arrive.

What happens if my worker crashes mid-processing?

The message is not deleted, so once its visibility timeout expires it becomes visible again and another consumer can process it. This is why SQS is reliable under worker failure.

Can I get duplicate messages?

On standard queues, yes - delivery is at-least-once, so duplicates are possible. Make your processing idempotent, or use a FIFO queue for exactly-once processing.

What is a dead-letter queue?

A separate queue that receives messages which failed processing a configured number of times. It stops poison messages from retrying forever and lets you inspect them.

How is SQS different from SNS?

SQS is pull: a worker receives and processes messages one group at a time. SNS is push: it delivers a copy to every subscriber. They are often combined in the fan-out pattern.

Processing takes longer than the timeout - what do I do?

Either set a longer VisibilityTimeout on the queue, or call ChangeMessageVisibility to extend the timeout for that message while you keep working, so it is not redelivered.

Can I receive more than one message at a time?

Yes. Set MaxNumberOfMessages up to 10 on ReceiveMessage to batch receives, and use DeleteMessageBatch to delete them together for fewer requests.

Amazon SNS via SDK: Your First Topic - the push half, and the fan-out source for queues.
AWS Lambda via SDK: Your First Function - a common queue consumer via event source mapping.
Core Services Basics - the one-call tour across all ten services.
Core AWS Services Best Practices - messaging defaults.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Amazon SQS via SDK: Your First Queue

Search Documentation

Amazon SQS via SDK: Your First Queue