taler-docs

commit c0e2d941f3cd51ac72befc1d753f74f91efc6001
parent 585b70aff0cc381e70f9f523691095980a9588d5
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Thu,  6 Nov 2025 17:21:20 +0100

update API mailbox

Diffstat:
M
core/api-mailbox.rst
 | 
28
++++++++++++++++++++--------

1 file changed, 20 insertions(+), 8 deletions(-)
diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst
@@ -27,7 +27,7 @@ without having to interact with the respective messaging service.
 
 Clients (wallets) are expected to generate mailbox keys that uniquely identify
 a mailbox as well as encryption keys that can be used to encrypt messages for
-the mailbox (e.g. `HPKE <https://www.rfc-editor.org/rfc/rfc9180.html>`.
+the mailbox (e.g. `HPKE <https://www.rfc-editor.org/rfc/rfc9180.html>`_.
 Mailbox signing keys are usable implicity, but encryption keys must be generated
 and put into the key directory.
 
@@ -96,7 +96,7 @@ Sending messages
 
   The content of the request must be the message with a size of
   exactly message_body_bytes (see `VersionResponse`).
-  The header `Mailbox-Order-Id` may be provided if the client recently
+  The header ``Mailbox-Order-Id`` may be provided if the client recently
   paid for this message.
 
   **Response**
@@ -107,7 +107,7 @@ Sending messages
      Client needs to make a Taler payment before proceeding. See
      standard Taler payment procedure.
   :http:statuscode:`403 Forbidden`
-     The specified order ID in the `Mailbox-Order-Id` header does not
+     The specified order ID in the ``Mailbox-Order-Id`` header does not
      permit sending of this message. Possible reasons include the order
      being for a different message, unpaid or
      malformed.
@@ -147,7 +147,10 @@ Receiving messages
   returned again (or possibly more if additional messages arrived
   and the total number is below the service's current internal limit).
   To receive additional messages, the client generally has to first
-  explicitly DELETE already downloaded messages from the mailbox.
+  explicitly delete already downloaded messages from the mailbox.
+  If messages are returned, the ``ETag`` header will be set
+  containing the ID of the first message
+  for use in any potential delete requests that require the message ID.
 
   **Request:**
 
@@ -172,15 +175,24 @@ Receiving messages
     load and is unable to accept the message for delivery.
     The response format is given by `MailboxRateLimitedResponse`_.
 
-.. http:delete:: /$ADDRESS
+.. http:post:: /private/$ADDRESS
 
   Requests the deletion of already received messages from the
   mailbox. Here, ``$ADDRESS`` must be the EdDSA public key
   of the mailbox (not the hash!).
+  The ``ETag`` header returned by a GET request for messages
+  returns the ID for the first message received.
+  This allows the caller to select a range of messages starting
+  from the first message received in the last GET call
+  to delete.
 
   **Request**
 
-  The body of the request must be a ``MessageDeletionRequest``.
+  The body of the request must be a `MessageDeletionRequest`_.
+  The header ``Match-If`` must be set to the ID of the first message
+  to delete.
+  For example, a ``Match-If`` header value of 2 and a count field of
+  5 will delete messages from ID 2 to 7 (given a valid signature).
 
   **Details:**
 
@@ -269,8 +281,8 @@ Key directory
       encryptionKeyType: "X25519";
 
       // Expiration of this mapping.
-      // Unix epoch (seconds) FIXME Timestamp?
-      expiration: number;
+      // Unix epoch (seconds)
+      expiration: Timestamp;
 
     }