get-H_MAILBOX.rst (1570B)
1 .. http:get:: /$H_MAILBOX 2 3 Endpoint that returns unread messages in ``$H_MAILBOX``. 4 The number of messages returned by the service can be limited. 5 If the request is simply repeated, the same messages will be 6 returned again (or possibly more if additional messages arrived 7 and the total number is below the service's current internal limit). 8 To receive additional messages, the client generally has to first 9 explicitly delete already downloaded messages from the mailbox. 10 If messages are returned, the ``ETag`` header will be set 11 containing the ID of the first message 12 for use in any potential delete requests that require the message ID. 13 14 **Request:** 15 16 :query timeout_ms=NUMBER: *Optional.* If specified, 17 the Mailbox service will wait up to ``NUMBER`` 18 milliseconds for the arrival of new messages 19 before sending the HTTP response. Note that if the 20 mailbox is non-empty, the service will always return 21 immediately with the messages in the mailbox, and not 22 wait for additional messages to arrive. 23 24 **Response** 25 26 :http:statuscode:`200 Ok`: 27 Messages are returned in binary format, 256 bytes per message, 28 starting with the ephemeral key and followed by 29 the encrypted body. Messages are not encapsulated in JSON! 30 :http:statuscode:`204 No Content`: 31 The mailbox is empty. 32 :http:statuscode:`429 Too Many Requests`: 33 The system is currently experiencing a too high request 34 load and is unable to accept the message for delivery. 35 The response format is given by :ref:`MailboxRateLimitedResponse`.