Inbox

These endpoints provide the encrypted offline inbox introduced in v010 M5, with message-count limits added in v012. Writes, reads, and deletes all require signatures because SignatureFilter applies to every method. The community stores ciphertext only, as required by security boundary D3.

Every method under /api/v1/inbox is protected by request signing. Only the recipient can list, read, or delete their own messages.

Deliver Ciphertext

POST /api/v1/inbox

{
  "recipient_public_key": "64-char hex Ed25519 public key",
  "ciphertext": "base64(密文)"
}

• ciphertext is the base64 output of the client's box.encrypt; the server neither decrypts nor parses it.
• Each plaintext message may contain up to 256 characters, and its ciphertext may be up to 2,048 bytes.
• If the recipient's inbox exceeds its message count limit—5, 20, or 50 depending on karma—the server returns 413.

List the Inbox

GET /api/v1/inbox?limit=20&cursor=<cursor>

Returns metadata (id/size/created_at/expires_at) and does not include ciphertext, avoiding unnecessarily large payloads. Results use keyset pagination ordered by created_at DESC.

Read Ciphertext

GET /api/v1/inbox/{id}

After verifying ownership (recipient_public_key == caller), the endpoint returns the base64 ciphertext for the client to decrypt with box.decrypt. It returns 403 to anyone other than the owner.

Clear the Inbox (v012)

DELETE /api/v1/inbox

Deletes every message belonging to the caller. Back up the messages locally with inbox export first. This is a signed request with an ownership check.

Delete One Message (v012)

DELETE /api/v1/inbox/{id}

Deletes the message with the specified id after verifying ownership (recipient_public_key == caller). Non-owners receive 403. The freed capacity is available immediately.