0
# Message Operations
1

2
Message operations provide the core functionality for sending, receiving, and deleting messages in Amazon SQS queues. This includes both individual message operations and efficient batch operations for high-throughput scenarios.
3

4
## Send Messages
5

6
### Send Single Message
7

8
Send individual messages to a queue with optional attributes and configuration.
9

10
```java { .api }
11
SendMessageResult sendMessage(SendMessageRequest request);
12

13
// Convenience method
14
SendMessageResult sendMessage(String queueUrl, String messageBody);
15

16
class SendMessageRequest extends AmazonWebServiceRequest {
17
    SendMessageRequest();
18
    SendMessageRequest(String queueUrl, String messageBody);
19
    
20
    String getQueueUrl();
21
    SendMessageRequest withQueueUrl(String queueUrl);
22
    
23
    String getMessageBody();
24
    SendMessageRequest withMessageBody(String messageBody);
25
    
26
    Integer getDelaySeconds();
27
    SendMessageRequest withDelaySeconds(Integer delaySeconds);
28
    
29
    Map<String, MessageAttributeValue> getMessageAttributes();
30
    SendMessageRequest withMessageAttributes(Map<String, MessageAttributeValue> messageAttributes);
31
    SendMessageRequest addMessageAttributesEntry(String key, MessageAttributeValue value);
32
    
33
    Map<String, MessageSystemAttributeValue> getMessageSystemAttributes();
34
    SendMessageRequest withMessageSystemAttributes(Map<String, MessageSystemAttributeValue> messageSystemAttributes);
35
    
36
    // FIFO queue specific
37
    String getMessageDeduplicationId();
38
    SendMessageRequest withMessageDeduplicationId(String messageDeduplicationId);
39
    
40
    String getMessageGroupId();
41
    SendMessageRequest withMessageGroupId(String messageGroupId);
42
}
43

44
class SendMessageResult {
45
    String getMD5OfBody();
46
    String getMD5OfMessageAttributes();
47
    String getMessageId();
48
    String getSequenceNumber(); // FIFO queues only
49
}
50
```
51

52
**Usage Example:**
53

54
```java
55
// Basic message send
56
SendMessageRequest request = new SendMessageRequest()
57
    .withQueueUrl("https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue")
58
    .withMessageBody("Hello, SQS!");
59

60
SendMessageResult result = client.sendMessage(request);
61
System.out.println("Message ID: " + result.getMessageId());
62

63
// Message with attributes
64
MessageAttributeValue attribute = new MessageAttributeValue()
65
    .withDataType("String")
66
    .withStringValue("OrderProcessing");
67

68
SendMessageRequest requestWithAttrs = new SendMessageRequest()
69
    .withQueueUrl(queueUrl)
70
    .withMessageBody("Order data: {...}")
71
    .addMessageAttributesEntry("MessageType", attribute)
72
    .withDelaySeconds(30); // Delay 30 seconds
73

74
client.sendMessage(requestWithAttrs);
75

76
// FIFO queue message
77
SendMessageRequest fifoRequest = new SendMessageRequest()
78
    .withQueueUrl("https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue.fifo")
79
    .withMessageBody("FIFO message")
80
    .withMessageGroupId("group1")
81
    .withMessageDeduplicationId("unique-id-123");
82

83
client.sendMessage(fifoRequest);
84
```
85

86
### Send Batch Messages
87

88
Send up to 10 messages in a single API call for improved throughput and cost efficiency.
89

90
```java { .api }
91
SendMessageBatchResult sendMessageBatch(SendMessageBatchRequest request);
92

93
// Convenience method
94
SendMessageBatchResult sendMessageBatch(String queueUrl, List<SendMessageBatchRequestEntry> entries);
95

96
class SendMessageBatchRequest extends AmazonWebServiceRequest {
97
    String getQueueUrl();
98
    SendMessageBatchRequest withQueueUrl(String queueUrl);
99
    
100
    List<SendMessageBatchRequestEntry> getEntries();
101
    SendMessageBatchRequest withEntries(List<SendMessageBatchRequestEntry> entries);
102
    SendMessageBatchRequest withEntries(SendMessageBatchRequestEntry... entries);
103
}
104

105
class SendMessageBatchRequestEntry {
106
    String getId();
107
    SendMessageBatchRequestEntry withId(String id);
108
    
109
    String getMessageBody();
110
    SendMessageBatchRequestEntry withMessageBody(String messageBody);
111
    
112
    Integer getDelaySeconds();
113
    SendMessageBatchRequestEntry withDelaySeconds(Integer delaySeconds);
114
    
115
    Map<String, MessageAttributeValue> getMessageAttributes();
116
    SendMessageBatchRequestEntry withMessageAttributes(Map<String, MessageAttributeValue> messageAttributes);
117
    
118
    String getMessageDeduplicationId();
119
    SendMessageBatchRequestEntry withMessageDeduplicationId(String messageDeduplicationId);
120
    
121
    String getMessageGroupId();
122
    SendMessageBatchRequestEntry withMessageGroupId(String messageGroupId);
123
}
124

125
class SendMessageBatchResult {
126
    List<SendMessageBatchResultEntry> getSuccessful();
127
    List<BatchResultErrorEntry> getFailed();
128
}
129

130
class SendMessageBatchResultEntry {
131
    String getId();
132
    String getMD5OfBody();
133
    String getMD5OfMessageAttributes();
134
    String getMessageId();
135
    String getSequenceNumber();
136
}
137
```
138

139
**Usage Example:**
140

141
```java
142
// Create batch entries
143
List<SendMessageBatchRequestEntry> entries = Arrays.asList(
144
    new SendMessageBatchRequestEntry()
145
        .withId("msg1")
146
        .withMessageBody("First message"),
147
    new SendMessageBatchRequestEntry()
148
        .withId("msg2")
149
        .withMessageBody("Second message")
150
        .withDelaySeconds(60),
151
    new SendMessageBatchRequestEntry()
152
        .withId("msg3")
153
        .withMessageBody("Third message")
154
        .addMessageAttributesEntry("Priority", 
155
            new MessageAttributeValue().withDataType("String").withStringValue("High"))
156
);
157

158
SendMessageBatchRequest batchRequest = new SendMessageBatchRequest()
159
    .withQueueUrl(queueUrl)
160
    .withEntries(entries);
161

162
SendMessageBatchResult batchResult = client.sendMessageBatch(batchRequest);
163

164
// Process results
165
for (SendMessageBatchResultEntry success : batchResult.getSuccessful()) {
166
    System.out.println("Sent message: " + success.getId() + " -> " + success.getMessageId());
167
}
168

169
for (BatchResultErrorEntry error : batchResult.getFailed()) {
170
    System.err.println("Failed message: " + error.getId() + " - " + error.getMessage());
171
}
172
```
173

174
## Receive Messages
175

176
### Receive Messages from Queue
177

178
Retrieve messages from a queue with configurable options for long polling, message attributes, and batch size.
179

180
```java { .api }
181
ReceiveMessageResult receiveMessage(ReceiveMessageRequest request);
182

183
// Convenience method
184
ReceiveMessageResult receiveMessage(String queueUrl);
185

186
class ReceiveMessageRequest extends AmazonWebServiceRequest {
187
    ReceiveMessageRequest();
188
    ReceiveMessageRequest(String queueUrl);
189
    
190
    String getQueueUrl();
191
    ReceiveMessageRequest withQueueUrl(String queueUrl);
192
    
193
    List<String> getAttributeNames();
194
    ReceiveMessageRequest withAttributeNames(List<String> attributeNames);
195
    ReceiveMessageRequest withAttributeNames(String... attributeNames);
196
    ReceiveMessageRequest withAttributeNames(QueueAttributeName... attributeNames);
197
    
198
    List<String> getMessageAttributeNames();
199
    ReceiveMessageRequest withMessageAttributeNames(List<String> messageAttributeNames);
200
    ReceiveMessageRequest withMessageAttributeNames(String... messageAttributeNames);
201
    
202
    Integer getMaxNumberOfMessages();
203
    ReceiveMessageRequest withMaxNumberOfMessages(Integer maxNumberOfMessages);
204
    
205
    Integer getVisibilityTimeout();
206
    ReceiveMessageRequest withVisibilityTimeout(Integer visibilityTimeout);
207
    
208
    Integer getWaitTimeSeconds();
209
    ReceiveMessageRequest withWaitTimeSeconds(Integer waitTimeSeconds);
210
    
211
    String getReceiveRequestAttemptId();
212
    ReceiveMessageRequest withReceiveRequestAttemptId(String receiveRequestAttemptId);
213
}
214

215
class ReceiveMessageResult {
216
    List<Message> getMessages();
217
}
218

219
class Message {
220
    String getMessageId();
221
    String getReceiptHandle();
222
    String getMD5OfBody();
223
    String getBody();
224
    Map<String, String> getAttributes();
225
    String getMD5OfMessageAttributes();
226
    Map<String, MessageAttributeValue> getMessageAttributes();
227
}
228
```
229

230
**Usage Example:**
231

232
```java
233
// Basic message receive
234
ReceiveMessageRequest request = new ReceiveMessageRequest(queueUrl);
235
ReceiveMessageResult result = client.receiveMessage(request);
236

237
for (Message message : result.getMessages()) {
238
    System.out.println("Received: " + message.getBody());
239
    // Process message...
240
}
241

242
// Advanced receive with long polling and attributes
243
ReceiveMessageRequest advancedRequest = new ReceiveMessageRequest()
244
    .withQueueUrl(queueUrl)
245
    .withMaxNumberOfMessages(10)
246
    .withWaitTimeSeconds(20) // Long polling
247
    .withVisibilityTimeout(60) // 1 minute visibility
248
    .withAttributeNames(QueueAttributeName.All)
249
    .withMessageAttributeNames("All");
250

251
ReceiveMessageResult advancedResult = client.receiveMessage(advancedRequest);
252

253
for (Message message : advancedResult.getMessages()) {
254
    System.out.println("Message ID: " + message.getMessageId());
255
    System.out.println("Body: " + message.getBody());
256
    System.out.println("Receipt Handle: " + message.getReceiptHandle());
257
    
258
    // Access message attributes
259
    for (Map.Entry<String, MessageAttributeValue> attr : message.getMessageAttributes().entrySet()) {
260
        System.out.println("Attribute " + attr.getKey() + ": " + attr.getValue().getStringValue());
261
    }
262
    
263
    // Access system attributes
264
    for (Map.Entry<String, String> attr : message.getAttributes().entrySet()) {
265
        System.out.println("System attribute " + attr.getKey() + ": " + attr.getValue());
266
    }
267
}
268
```
269

270
## Delete Messages
271

272
### Delete Single Message
273

274
Remove processed messages from the queue using receipt handles.
275

276
```java { .api }
277
DeleteMessageResult deleteMessage(DeleteMessageRequest request);
278

279
// Convenience method
280
DeleteMessageResult deleteMessage(String queueUrl, String receiptHandle);
281

282
class DeleteMessageRequest extends AmazonWebServiceRequest {
283
    DeleteMessageRequest();
284
    DeleteMessageRequest(String queueUrl, String receiptHandle);
285
    
286
    String getQueueUrl();
287
    DeleteMessageRequest withQueueUrl(String queueUrl);
288
    
289
    String getReceiptHandle();
290
    DeleteMessageRequest withReceiptHandle(String receiptHandle);
291
}
292

293
class DeleteMessageResult {
294
    // Empty result class - success indicated by no exception
295
}
296
```
297

298
**Usage Example:**
299

300
```java
301
// Receive and delete pattern
302
ReceiveMessageResult receiveResult = client.receiveMessage(new ReceiveMessageRequest(queueUrl));
303

304
for (Message message : receiveResult.getMessages()) {
305
    try {
306
        // Process the message
307
        processMessage(message);
308
        
309
        // Delete after successful processing
310
        client.deleteMessage(new DeleteMessageRequest()
311
            .withQueueUrl(queueUrl)
312
            .withReceiptHandle(message.getReceiptHandle()));
313
        
314
        System.out.println("Deleted message: " + message.getMessageId());
315
    } catch (Exception e) {
316
        System.err.println("Failed to process message: " + e.getMessage());
317
        // Don't delete - message will become visible again
318
    }
319
}
320
```
321

322
### Delete Batch Messages
323

324
Delete up to 10 messages in a single API call.
325

326
```java { .api }
327
DeleteMessageBatchResult deleteMessageBatch(DeleteMessageBatchRequest request);
328

329
// Convenience method
330
DeleteMessageBatchResult deleteMessageBatch(String queueUrl, List<DeleteMessageBatchRequestEntry> entries);
331

332
class DeleteMessageBatchRequest extends AmazonWebServiceRequest {
333
    String getQueueUrl();
334
    DeleteMessageBatchRequest withQueueUrl(String queueUrl);
335
    
336
    List<DeleteMessageBatchRequestEntry> getEntries();
337
    DeleteMessageBatchRequest withEntries(List<DeleteMessageBatchRequestEntry> entries);
338
    DeleteMessageBatchRequest withEntries(DeleteMessageBatchRequestEntry... entries);
339
}
340

341
class DeleteMessageBatchRequestEntry {
342
    String getId();
343
    DeleteMessageBatchRequestEntry withId(String id);
344
    
345
    String getReceiptHandle();
346
    DeleteMessageBatchRequestEntry withReceiptHandle(String receiptHandle);
347
}
348

349
class DeleteMessageBatchResult {
350
    List<DeleteMessageBatchResultEntry> getSuccessful();
351
    List<BatchResultErrorEntry> getFailed();
352
}
353

354
class DeleteMessageBatchResultEntry {
355
    String getId();
356
}
357
```
358

359
**Usage Example:**
360

361
```java
362
// Batch delete after processing
363
List<DeleteMessageBatchRequestEntry> deleteEntries = new ArrayList<>();
364
ReceiveMessageResult receiveResult = client.receiveMessage(new ReceiveMessageRequest(queueUrl));
365

366
for (Message message : receiveResult.getMessages()) {
367
    try {
368
        // Process message
369
        processMessage(message);
370
        
371
        // Add to batch delete list
372
        deleteEntries.add(new DeleteMessageBatchRequestEntry()
373
            .withId(message.getMessageId())
374
            .withReceiptHandle(message.getReceiptHandle()));
375
            
376
    } catch (Exception e) {
377
        System.err.println("Skipping delete for failed message: " + message.getMessageId());
378
    }
379
}
380

381
// Perform batch delete
382
if (!deleteEntries.isEmpty()) {
383
    DeleteMessageBatchRequest deleteRequest = new DeleteMessageBatchRequest()
384
        .withQueueUrl(queueUrl)
385
        .withEntries(deleteEntries);
386
    
387
    DeleteMessageBatchResult deleteResult = client.deleteMessageBatch(deleteRequest);
388
    
389
    System.out.println("Successfully deleted: " + deleteResult.getSuccessful().size() + " messages");
390
    
391
    for (BatchResultErrorEntry error : deleteResult.getFailed()) {
392
        System.err.println("Failed to delete: " + error.getId() + " - " + error.getMessage());
393
    }
394
}
395
```
396

397
## Message Attributes
398

399
### Working with Message Attributes
400

401
Add custom metadata to messages for routing, processing, and filtering.
402

403
```java { .api }
404
class MessageAttributeValue {
405
    String getStringValue();
406
    MessageAttributeValue withStringValue(String stringValue);
407
    
408
    java.nio.ByteBuffer getBinaryValue();
409
    MessageAttributeValue withBinaryValue(java.nio.ByteBuffer binaryValue);
410
    
411
    List<String> getStringListValues();
412
    MessageAttributeValue withStringListValues(List<String> stringListValues);
413
    
414
    List<java.nio.ByteBuffer> getBinaryListValues();
415
    MessageAttributeValue withBinaryListValues(List<java.nio.ByteBuffer> binaryListValues);
416
    
417
    String getDataType();
418
    MessageAttributeValue withDataType(String dataType);
419
}
420
```
421

422
**Usage Example:**
423

424
```java
425
// Create various attribute types
426
Map<String, MessageAttributeValue> attributes = new HashMap<>();
427

428
// String attribute
429
attributes.put("MessageType", new MessageAttributeValue()
430
    .withDataType("String")
431
    .withStringValue("Order"));
432

433
// Number attribute
434
attributes.put("Priority", new MessageAttributeValue()
435
    .withDataType("Number")
436
    .withStringValue("5"));
437

438
// Binary attribute
439
attributes.put("Thumbnail", new MessageAttributeValue()
440
    .withDataType("Binary")
441
    .withBinaryValue(ByteBuffer.wrap(imageBytes)));
442

443
// String list attribute
444
attributes.put("Tags", new MessageAttributeValue()
445
    .withDataType("String.Array")
446
    .withStringListValues(Arrays.asList("urgent", "customer-order")));
447

448
// Send message with attributes
449
SendMessageRequest request = new SendMessageRequest()
450
    .withQueueUrl(queueUrl)
451
    .withMessageBody("Order data")
452
    .withMessageAttributes(attributes);
453

454
client.sendMessage(request);
455
```
456

457
## Error Handling
458

459
Common exceptions and error handling patterns for message operations:
460

461
```java
462
try {
463
    SendMessageResult result = client.sendMessage(request);
464
} catch (InvalidMessageContentsException e) {
465
    // Message body contains invalid characters
466
    System.err.println("Invalid message content: " + e.getMessage());
467
} catch (QueueDoesNotExistException e) {
468
    // Queue URL is invalid or queue was deleted
469
    System.err.println("Queue not found: " + e.getMessage());
470
} catch (UnsupportedOperationException e) {
471
    // Operation not supported (e.g., invalid queue type)
472
    System.err.println("Unsupported operation: " + e.getMessage());
473
}
474

475
// Batch operation error handling
476
try {
477
    SendMessageBatchResult result = client.sendMessageBatch(batchRequest);
478
    
479
    // Check for partial failures
480
    if (!result.getFailed().isEmpty()) {
481
        for (BatchResultErrorEntry error : result.getFailed()) {
482
            System.err.println("Batch entry " + error.getId() + " failed: " + 
483
                error.getCode() + " - " + error.getMessage());
484
        }
485
    }
486
} catch (EmptyBatchRequestException e) {
487
    System.err.println("Batch request was empty");
488
} catch (TooManyEntriesInBatchRequestException e) {
489
    System.err.println("Too many entries in batch (max 10)");
490
} catch (BatchEntryIdsNotDistinctException e) {
491
    System.err.println("Batch entry IDs must be unique");
492
}
493
```