Send, receive and delete SQS messages with the AWS SDK for Go v2, with long polling, visibility timeouts, batch deletes, dead-letter queues and a graceful consumer loop.

Amazon SQS is the queue most Go services on AWS start with, and sending a message with the AWS SDK for Go v2 takes a few lines. The consumer takes more care, with long polling, visibility timeouts, batch deletes and a loop that stops cleanly on SIGTERM.
This guide writes both sides with the SDK, then shows the same producer and consumer as typed Pub/Sub on SNS and SQS that is provisioned for you.
Encore is a backend framework with built-in infrastructure, and its Pub/Sub API covers the producer and consumer in a few declarations. On AWS each topic becomes an SNS topic and each subscription its own SQS queue with a dead-letter queue, so the loop, the deletes and the redrive are not code you maintain.

Run in your terminal to get started locally.
The orders service declares the topic and publishes from an endpoint:
// orders/orders.go
package orders
import (
"context"
"encore.dev/pubsub"
)
type OrderPlaced struct {
OrderID string `json:"order_id"`
Email string `json:"email"`
}
// SNS with an SQS queue per subscription on AWS, Pub/Sub on GCP,
// an in-process broker under encore run.
var OrderPlacedTopic = pubsub.NewTopic[*OrderPlaced]("order-placed", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
type PlaceParams struct {
OrderID string `json:"order_id"`
Email string `json:"email"`
}
type PlaceResponse struct {
MessageID string `json:"message_id"`
}
//encore:api public method=POST path=/orders
func Place(ctx context.Context, p *PlaceParams) (*PlaceResponse, error) {
id, err := OrderPlacedTopic.Publish(ctx, &OrderPlaced{OrderID: p.OrderID, Email: p.Email})
if err != nil {
return nil, err
}
return &PlaceResponse{MessageID: id}, nil
}
The email service subscribes, with AckDeadline in the role of the visibility timeout, MaxConcurrency caps parallel handlers, and after MaxRetries failed attempts the message moves to the subscription's dead-letter queue. The handler skips orders it already confirmed, because delivery is at least once:
// email/email.go
package email
import (
"context"
"sync"
"time"
"encore.app/orders"
"encore.dev/pubsub"
"encore.dev/rlog"
)
// sent stands in for a table with a unique order_id column.
var (
mu sync.Mutex
sent = map[string]bool{}
)
var _ = pubsub.NewSubscription(orders.OrderPlacedTopic, "send-confirmation",
pubsub.SubscriptionConfig[*orders.OrderPlaced]{
Handler: sendConfirmation,
AckDeadline: 60 * time.Second,
MaxConcurrency: 20,
RetryPolicy: &pubsub.RetryPolicy{
MinBackoff: 10 * time.Second,
MaxBackoff: 5 * time.Minute,
MaxRetries: 5, // then the dead-letter queue
},
},
)
func sendConfirmation(ctx context.Context, evt *orders.OrderPlaced) error {
mu.Lock()
defer mu.Unlock()
if sent[evt.OrderID] {
return nil // duplicate delivery
}
rlog.Info("sending confirmation", "order_id", evt.OrderID, "email", evt.Email)
sent[evt.OrderID] = true
return nil // returning an error retries with backoff
}
Under encore run, posting the same order twice logs one confirmation, and the trace for the request shows the publish and the handler as one timeline:
Tests check publishing without running subscribers: et.Topic(OrderPlacedTopic).PublishedMessages() returns what a test published, isolated per test. On deploy to your own AWS account, Encore creates the topic, queues and dead-letter queues, and provisions an IAM role for the service with publish and consume permissions on them.
The topic and its subscribers are declarations in the code, so a coding agent can add a second consumer in the same change as the handler, run it under encore run and watch both receive the event before anything touches AWS.
Best fit: Go services that want SQS-backed messaging with typed events, retries and a dead-letter queue per consumer in their own AWS account.
The SDK client loads credentials from the default chain: environment variables, the shared config file, SSO, or the role of the ECS task, Lambda function or EC2 instance. These examples use github.com/aws/aws-sdk-go-v2/service/sqs v1.53.
SendMessage takes a string body, so the event is marshaled to JSON first. Message attributes carry metadata a consumer can read without parsing the body:
type OrderPlaced struct {
OrderID string `json:"order_id"`
Email string `json:"email"`
}
func sendOrder(ctx context.Context, client *sqs.Client, queueURL string, evt OrderPlaced) error {
body, err := json.Marshal(evt)
if err != nil {
return err
}
_, err = client.SendMessage(ctx, &sqs.SendMessageInput{
QueueUrl: aws.String(queueURL),
MessageBody: aws.String(string(body)),
MessageAttributes: map[string]types.MessageAttributeValue{
"type": {DataType: aws.String("String"), StringValue: aws.String("order.placed")},
},
})
return err
}
The consumer is a loop around ReceiveMessage. WaitTimeSeconds: 20 turns on long polling, which waits for messages instead of returning empty responses you pay for. A message only leaves the queue when you delete it, so the loop collects successful receipt handles and deletes them in one batch:
func consume(ctx context.Context, client *sqs.Client, queueURL string, handle func(context.Context, OrderPlaced) error) error {
for {
out, err := client.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{
QueueUrl: aws.String(queueURL),
MaxNumberOfMessages: 10,
WaitTimeSeconds: 20, // long polling
VisibilityTimeout: 60, // seconds to finish before redelivery
MessageAttributeNames: []string{"All"},
})
if errors.Is(ctx.Err(), context.Canceled) {
return nil // shutting down
}
if err != nil {
return err
}
var done []types.DeleteMessageBatchRequestEntry
for _, m := range out.Messages {
var evt OrderPlaced
if err := json.Unmarshal([]byte(aws.ToString(m.Body)), &evt); err != nil {
log.Printf("bad message %s: %v", aws.ToString(m.MessageId), err)
continue // the redrive policy moves it to the DLQ
}
if err := handle(ctx, evt); err != nil {
log.Printf("order %s failed: %v", evt.OrderID, err)
continue // visible again after the timeout
}
done = append(done, types.DeleteMessageBatchRequestEntry{
Id: m.MessageId,
ReceiptHandle: m.ReceiptHandle,
})
}
if len(done) > 0 {
res, err := client.DeleteMessageBatch(ctx, &sqs.DeleteMessageBatchInput{
QueueUrl: aws.String(queueURL),
Entries: done,
})
if err != nil {
return err
}
for _, f := range res.Failed {
log.Printf("delete failed for %s: %s", aws.ToString(f.Id), aws.ToString(f.Message))
}
}
}
}
DeleteMessageBatch can partly fail while returning no error, which is why the loop checks res.Failed; an entry that fails to delete is redelivered later, and the handler has to tolerate that. main wires the client to a context that is cancelled on SIGTERM, so ECS or Kubernetes can stop the consumer between polls:
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
log.Fatal(err)
}
client := sqs.NewFromConfig(cfg)
err = consume(ctx, client, os.Getenv("ORDERS_QUEUE_URL"), func(ctx context.Context, evt OrderPlaced) error {
log.Printf("sending confirmation for %s to %s", evt.OrderID, evt.Email)
return nil
})
if err != nil {
log.Fatal(err)
}
}
The queue itself comes from outside the code, and a redrive policy with maxReceiveCount moves a message to a dead-letter queue after that many receives, and the visibility timeout should exceed the slowest handler, or a message is processed twice while the first attempt is still running. The consumer's role needs sqs:ReceiveMessage and sqs:DeleteMessage on the queue, plus sqs:ChangeMessageVisibility if it extends timeouts, and the producer's needs sqs:SendMessage.
For more than one consumer of the same event, the usual shape is an SNS topic with one SQS queue subscribed per consumer, which is more resources and more policies for each new subscriber.
Best fit: Go services that already have their queues defined in Terraform or CloudFormation and need full control over receive, batching and visibility.
Use the SDK directly when the queues already exist, when you need SQS features such as FIFO message groups or per-message visibility changes, or when the consumer is part of a larger system you do not control. Use Encore when the queue exists to connect your own services, since topics, subscriptions, dead-letter queues and IAM come from the same Go declarations that run locally under encore run.
Create a client with sqs.NewFromConfig and call ReceiveMessage in a loop with MaxNumberOfMessages up to 10 and WaitTimeSeconds 20 for long polling. Process each message, then delete it with DeleteMessage or DeleteMessageBatch using its receipt handle; anything not deleted becomes visible again after the visibility timeout.
Standard queues deliver at least once, and a message also reappears when your consumer does not delete it before the visibility timeout ends. Make the handler idempotent, for example by recording processed IDs under a unique key, and set the visibility timeout longer than the slowest handler.
sqs:ReceiveMessage and sqs:DeleteMessage on the queue, plus sqs:ChangeMessageVisibility if it extends the timeout and sqs:GetQueueAttributes if it reads attributes. A producer needs sqs:SendMessage. Grant them to the role the task or function runs as rather than to access keys.
Declare a topic with pubsub.NewTopic and a subscription with pubsub.NewSubscription and a handler function. On AWS, Encore provisions an SNS topic with an SQS queue and a dead-letter queue per subscription, runs the receive and delete loop for you, and retries a message when the handler returns an error.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.