> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openpayload.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get cached messages

> Retrieve pending encrypted envelopes for a recipient using a signed Cache access proof

This endpoint returns encrypted messages waiting for one recipient DID. It does not decrypt them.

Because a DID is public, the DID alone is not authorization. Your client must sign a Cache retrieval proof with an Ed25519 verification method authorized by the recipient's `OpenPayloadCacheService`.

## Build the signed proof

Construct this exact UTF-8 string. Do not add a trailing newline:

```text theme={null}
openpayload:cache:retrieval-proof:v1
operation=pull
did=did:openpayload:1111111111111111111111
device_id=
service_id=did:openpayload:1111111111111111111111#cache
cache_endpoint=https://cache.example.com
key_id=did:openpayload:1111111111111111111111#signing
timestamp=<current-RFC3339-timestamp>
nonce=<unique-random-nonce>
subject=*
```

Sign those bytes with the authorized Ed25519 private key, then Base64-encode the signature.

The timestamp may be ISO-8601, epoch milliseconds, or epoch seconds and must fall within the Cache's permitted clock skew. Never reuse a nonce with the same operation, DID, and key.

## Request

<ParamField path="did" type="string" required>
  The recipient DID.
</ParamField>

<ParamField header="X-Service-Id" type="string" required>
  The authorized `OpenPayloadCacheService` ID.
</ParamField>

<ParamField header="X-Cache-Endpoint" type="string" required>
  The exact public Cache endpoint bound into the signature.
</ParamField>

<ParamField header="X-Key-Id" type="string" required>
  The authorized Ed25519 verification-method ID.
</ParamField>

<ParamField header="X-Timestamp" type="string" required>
  The signed timestamp.
</ParamField>

<ParamField header="X-Nonce" type="string" required>
  A new replay-resistant nonce.
</ParamField>

<ParamField header="X-Signature" type="string" required>
  Base64 Ed25519 signature over the exact proof text.
</ParamField>

<RequestExample>
  ```bash Request theme={null}
  curl --request GET \
    --url "https://cache.example.com/cache/messages/did%3Aopenpayload%3A1111111111111111111111" \
    --header "X-Service-Id: did:openpayload:1111111111111111111111#cache" \
    --header "X-Cache-Endpoint: https://cache.example.com" \
    --header "X-Key-Id: did:openpayload:1111111111111111111111#signing" \
    --header "X-Timestamp: <current-RFC3339-timestamp>" \
    --header "X-Nonce: <unique-random-nonce>" \
    --header "X-Signature: <base64-signature>"
  ```
</RequestExample>

## Response

```json 200 Response theme={null}
{
  "count": 1,
  "messages": [
    {
      "message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
      "recipient": "did:openpayload:1111111111111111111111",
      "expires_at": "2026-07-25T16:30:00Z",
      "chunked": false,
      "envelope": {
        "message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
        "to": "did:openpayload:1111111111111111111111",
        "timestamp": "2026-07-24T16:30:00Z",
        "expires_at": "2026-07-25T16:30:00Z",
        "payload": {"ciphertext_b64":"<encrypted-message>"}
      },
      "proof": {
        "event_type": "retrieval"
      }
    }
  ]
}
```

This response example shows ordinary DID-service fall-through. A policy-delivered envelope may also contain opaque [network-managed policy provenance](/guides/ddn-envelope#network-managed-policy-provenance). Treat it as transport metadata; do not modify it or resubmit it as client authorization.

## After retrieval

1. Verify the envelope and any sender signature your application requires.
2. Store it safely on the recipient device.
3. Decrypt it locally.
4. Record the Cache endpoint from which this copy was retrieved.
5. Acknowledge it at that Cache only after you no longer need the encrypted copy.

A Relay result can include observed Store endpoints in `details.accepted_caches` and Archive endpoints in `details.accepted_archives`. Those lists do not include later accepts after a `Forward` step and are not embedded in the stored envelope for the recipient. If the recipient retrieves replicas from more than one Cache, it acknowledges each copy at the Cache that returned it.

## Straight to the point

```http theme={null}
GET /cache/messages/{did}
```

Proof operation: `pull`\
Proof device: empty\
Proof subject: `*`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.