OpenPayload Relay API - OpenPayload Developer Network

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

A recipient OpenPayload DID or alias, optionally qualified by a Persona
The recipient’s current key-agreement information from a Directory
An encrypted payload
A valid DDN envelope
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.

See Relay discovery in a DID document

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

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

​What you need before sending

See Relay discovery in a DID document

​Which endpoint should I use?

​Policy resolution

​What success means

​Straight to the point

What you need before sending

Which endpoint should I use?

Policy resolution

What success means

Straight to the point