> ## 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.
# OpenPayload Relay API
> Send encrypted DDN messages without exposing their contents to the forwarding node
A Relay accepts an encrypted DDN envelope and attempts to move it toward the recipient. It is similar to a postal sorting point: it needs enough public information to route the parcel, but it does not need to open the parcel.
## What you need before sending
1. A recipient OpenPayload DID or alias, optionally qualified by a Persona
2. The recipient's current key-agreement information from a Directory
3. An encrypted payload
4. A valid [DDN envelope](/guides/ddn-envelope)
5. An HTTPS Relay base URL supplied by an operator or discovered through a public DID service
Resolve the recipient DID and select a service whose `type` is `OpenPayloadRelayService`. Treat each `serviceEndpoint` value as a Relay base URL, then append the public Relay route shown below.
Follow the Relay service from DID resolution through encrypted message submission.
## Which endpoint should I use?
| Endpoint | Use it when |
| - | - |
| `POST /relay` | The envelope's `to` or `recipient` field is the only target source |
| `POST /relay/{recipientDid}` | The envelope uses that same DID as its base target and you want URL binding |
Both routes call the same delivery service. On the path form, the path DID must equal the body target's base DID; an optional `@persona` suffix remains in the body. Use `POST /relay` when the body target begins with an alias.
## Policy resolution
Delivery behavior is resolved against finalized state for every client message so an ordinary DID policy is not skipped. Resolution includes the optional Persona and tag as selectors. Persona rules have precedence over DID rules; tags are match conditions rather than independent policy scopes.
A valid `applied: false` result means the Relay uses the DID's ordinary service entries. A Directory or chain failure is not a policy-free result and must not be silently bypassed.
The winning action can execute a `DeliveryPlan/v1`, reject delivery with a public reason code, or explicitly select base-DID delivery. `BaseDidDelivery/v1` applies the recipient's ordinary service routing once; a receiving Relay does not repeat Relay forwarding. A delivery plan can forward once, fork successor work, store, or archive the envelope at named services. A rule can only narrow the DID or Persona constraints and network ceilings.
The network pins the selected finalized revision for the delivery attempt. A plan can use one `Forward` step, and its successors run afterward under the same decision. Policies cannot create Forward-to-Forward chains. Clients do not submit policy provenance.
## What success means
The Relay returns a `DeliveryResult`. Success means the Relay completed the delivery plan requirements reported in that result. A `policy_handoff` delivery mode means the next Relay accepted responsibility; it does not confirm that later Store or Archive work has completed. For policy execution, `details` contains policy provenance and forwarded endpoints. `details.accepted_caches` reports accepted `Store` endpoints, and `details.accepted_archives` reports accepted `Archive` endpoints. Both lists cover only storage observed by the responding Relay and do not aggregate later accepts after a `Forward` step. Every accepted copy uses the same expiration upper bound.
Encrypt the header and payload before submission. A Relay endpoint is not an encryption service.
## Straight to the point
```text theme={null}
Content-Type: application/json
Body: one valid encrypted DDN envelope
Primary route: POST /relay
Recipient-bound route: POST /relay/{recipientDid}
Target syntax: did-or-alias[@persona], with tag as a separate field
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.