ReceiveMessage

Description

The ReceiveMessage action retrieves one or more messages from the specified queue. For each message returned, the response includes the following:

Message body
MD5 digest of the message body (for information about MD5, go to http://faqs.org/rfcs/rfc1321.html)
Message ID you received when you sent the message to the queue
Receipt handle

The receipt handle is the identifier you must provide when deleting the message (for more information, see Queue and Message Identifiers).

Note

	Note
Due to the distributed nature of the queue, a weighted random set of machines is sampled on a `ReceiveMessage` call. That means only the messages on the sampled machines are returned. If the number of messages in the queue is small (less than 1000), it is likely you will get fewer messages than you requested per `ReceiveMessage` call. If the number of messages in the queue is extremely small, you might not receive any messages in a particular `ReceiveMessage` response; in which case you should repeat the request.

Due to the distributed nature of the queue, a weighted random set of machines is sampled on a ReceiveMessage call. That means only the messages on the sampled machines are returned. If the number of messages in the queue is small (less than 1000), it is likely you will get fewer messages than you requested per ReceiveMessage call. If the number of messages in the queue is extremely small, you might not receive any messages in a particular ReceiveMessage response; in which case you should repeat the request.

You can provide the VisibilityTimeout parameter in your request, which will be applied to the messages that SQS returns in the response. If you do not include the parameter, the overall visibility timeout for the queue is used for the returned messages. For more information, see Visibility Timeout.

Request Parameters

The following table lists the special request parameters the ReceiveMessage action uses in addition to the common request parameters all actions use (for more information, see Request Parameters Common to All Actions).

Name Description Required

Name	Description	Required
`MaxNumberOfMessages`	Maximum number of messages to return. SQS never returns more messages than this value but might return fewer. Not necessarily all the messages in the queue are returned (for more information, see the preceding note about machine sampling). Type: Integer from 1 to 10 Default: 1	No
`VisibilityTimeout`	The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a `ReceiveMessage` request. Type: Integer from 0 to 7200, inclusive (maximum 2 hours) Default: The visibility timeout for the queue	No

MaxNumberOfMessages

Maximum number of messages to return. SQS never returns more messages than this value but might return fewer.

Not necessarily all the messages in the queue are returned (for more information, see the preceding note about machine sampling).

Type: Integer from 1 to 10

Default: 1

No

VisibilityTimeout

The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request.

Type: Integer from 0 to 7200, inclusive (maximum 2 hours)

Default: The visibility timeout for the queue

No

Response Elements

The following table lists the response elements the ReceiveMessage action returns in addition to the common response elements all actions return (for more information, see Structure of a Successful Response).

Name Description

Name	Description
`Message`	An element containing the information about the message. Ancestor: `ReceiveMessageResult` Children: Body—The message's contents (not URL encoded) MD5OfBody—An MD5 digest of the non-URL-encoded message body string MessageId—The message's SQS-assigned ID ReceiptHandle—A string associated with a specific instance of receiving the message

Message

An element containing the information about the message.

Ancestor: ReceiveMessageResult

Children:

Body—The message's contents (not URL encoded)
MD5OfBody—An MD5 digest of the non-URL-encoded message body string
MessageId—The message's SQS-assigned ID
ReceiptHandle—A string associated with a specific instance of receiving the message

Special Errors

The following table lists the special errors the ReceiveMessage action returns in addition to the common errors all actions return (for more information, see Errors Common to all Actions).

Error	Description	HTTP Status Code
`ReadCountOutOfRange`	The value for `MaxNumberOfMessages` is not valid (must be from 1 to 10).	400

Examples

The following example Query request receives messages from the specified queue.

Sample Request

http://queue.amazonaws.com/queue1
?Action=ReceiveMessage
&MaxNumberOfMessages=2
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2008-01-01
&Expires=2008-02-10T12:00:00Z
&Signature=CN2SbNq2B2Vw1W3lbc7wpM5gzDHEXAMPLE
&SignatureVersion=2
&SignatureMethod=HmacSHA256

Sample Response

<ReceiveMessageResponse>
  <ReceiveMessageResult>
    <Message>
      <MessageId>11YEJMCHE2DM483NGN40|3H4AA8J7EJKM0DQZR7E1|PT6DRTB278S4MNY77NJ0</MessageId>
      <ReceiptHandle>Z2hlcm1hbi5kZXNrdG9wLmFtYXpvbi5jb20=:AAABFoNJa/AAAAAAAAAANwAAAAAAAAAAAAAAAAAAAAQAAAEXAMPLE</ReceiptHandle>
      <MD5OfBody>acbd18db4cc2f85cedef654fccc4a4d8</MD5OfBody>
      <Body>foo</Body>
    </Message>
    <Message>
      <MessageId>0MKX1FF3JB8VWS8JAV79|3H4AA8J7EJKM0DQZR7E1|PT6DRTB278S4MNY77NJ0</MessageId>
      <ReceiptHandle>X5djmi3uoi2zZ8Vdr5TkmAQtDTwrcd9lx87=:AAABFoNJa/AAAAAAAAAANwAAAAAAAAAAAAAAAAAAAAQAAAEXAMPLE</ReceiptHandle>
      <MD5OfBody>37b51d194a7513e45b56f6524f2d51f2</MD5OfBody>
      <Body>bar</Body>
    </Message>
  </ReceiveMessageResult>
  <ResponseMetadata>
    <RequestId>b5bf2332-e983-4d3e-941a-f64c0d21f00f</RequestId>
  </ResponseMetadata>
</ReceiveMessageResponse>