ReceiveMessage

Description

Retrieves one or more messages from the specified queue, including the message body and message ID of each message. Messages returned by this action stay in the queue until you delete them. However, once a message is returned to a ReceiveMessage request, it is not returned on subsequent ReceiveMessage requests for the duration of the VisibilityTimeout. If you do not specify a VisibilityTimeout in the request, the overall visibility timeout for the queue is used for the returned messages. A default visibility timeout of 30 seconds is set when you create the queue. You can also set the visibility timeout for the queue by using SetQueueAttributes. See Visibility Timeout for more information.

	Note
	To view a message regardless of its visibility timeout state, use PeekMessage.

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. You can always peek on any specific message in the queue by using the PeekMessage action.

Request Parameters

The following table lists the special request parameters the action uses (in addition to the common request parameters listed in Common Request Parameters).

Name Description Required

Name	Description	Required
`NumberOfMessages`	Maximum number of messages to return. If there are fewer messages in the queue than `NumberOfMessages`, the maximum number of messages returned is the current number of messages in the queue. Not necessarily all the messages in the queue are returned. Type: Integer from 1 to 256 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. See Visibility Timeout for more information. Type: Integer from 0 to 86400 (maximum 24 hours) Default: The visibility timeout for the queue	No

NumberOfMessages

Maximum number of messages to return. If there are fewer messages in the queue than NumberOfMessages, the maximum number of messages returned is the current number of messages in the queue.

Not necessarily all the messages in the queue are returned.

Type: Integer from 1 to 256

Default: 1

VisibilityTimeout

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

Type: Integer from 0 to 86400 (maximum 24 hours)

Default: The visibility timeout for the queue

Response Elements

The following table lists the response elements the action returns (in addition to the common response elements listed in The Structure of a Response). See the Sample Response.

Name Description

Name	Description
`Message`	An element containing information about the message. See the example response below. Ancestor: `ReceiveMessageResponse` Child: `MessageId`, `MessageBody`
`MessageBody`	The message's contents. Type: String Ancestor: `Message`
`MessageId`	The message's system-assigned ID. Type: String Ancestor: `Message`

Message

An element containing information about the message. See the example response below.

Ancestor: ReceiveMessageResponse

Child: MessageId, MessageBody

MessageBody

The message's contents.

Type: String

Ancestor: Message

MessageId

The message's system-assigned ID.

Type: String

Ancestor: Message

Special Errors

The following table lists the special errors the action returns (in addition to the common errors listed in Common Errors).

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

Examples

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

Sample Request

http://queue.amazonaws.com/A29E9VSPHGOG23/queue1
?Action=ReceiveMessage
&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE
&Version=2007-05-01
&Expires=2007-05-12T12:00:00Z
&Signature=CN2SbNq%2B2Vw1W3lbc7wpM5gzDHEXAMPLE=
&NumberOfMessages=2

Sample Response

<ReceiveMessageResponse>
  <Message>
    <MessageId>11YEJMCHE2DM483NGN40|3H4AA8J7EJKM0DQZR7E1|PT6DRTB278S4MNY77NJ0</MessageId>
    <MessageBody>foo</MessageBody>
  </Message>
  <Message>
    <MessageId>0MKX1FF3JB8VWS8JAV79|3H4AA8J7EJKM0DQZR7E1|PT6DRTB278S4MNY77NJ0</MessageId>
    <MessageBody>bar</MessageBody>
  </Message>
  <ResponseStatus>
    <StatusCode>Success</StatusCode>
    <RequestId>b5bf2332-e983-4d3e-941a-f64c0d21f00f</RequestId>
  </ResponseStatus>
</ReceiveMessageResponse>