curl --request POST \
--url "https://relay.example.com/relay/did%3Aopenpayload%3A1111111111111111111111" \
--header "Content-Type: application/json" \
--data '{
"message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
"to": "did:openpayload:1111111111111111111111@example.com",
"tag": "Legal",
"timestamp": "<current-RFC3339-timestamp>",
"payload": {"ciphertext_b64":"<encrypted-message>"},
"encrypted_header": "<base64-encrypted-header>",
"header_nonce": "<base64-nonce>",
"header_key_id": "recipient-key-1",
"schema_version": "1"
}'
Relay API
Send to a path-bound recipient
Submit a DDN envelope while binding the recipient DID in both the URL and body
curl --request POST \
--url "https://relay.example.com/relay/did%3Aopenpayload%3A1111111111111111111111" \
--header "Content-Type: application/json" \
--data '{
"message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
"to": "did:openpayload:1111111111111111111111@example.com",
"tag": "Legal",
"timestamp": "<current-RFC3339-timestamp>",
"payload": {"ciphertext_b64":"<encrypted-message>"},
"encrypted_header": "<base64-encrypted-header>",
"header_nonce": "<base64-nonce>",
"header_key_id": "recipient-key-1",
"schema_version": "1"
}'
This route behaves like
The body is the same encrypted DDN envelope accepted by
POST /relay, with one additional safety check: the URL declares the expected base recipient DID. The Relay rejects a message when the body target does not begin with that same DID. An optional @persona suffix does not change the comparison. Use POST /relay for an alias target.
This is helpful when your application routes requests per recipient or wants to detect an accidental body mix-up.
Request
string
required
The URL-encoded recipient DID. It must equal the DID before any optional
@persona suffix in to or recipient.POST /relay.
curl --request POST \
--url "https://relay.example.com/relay/did%3Aopenpayload%3A1111111111111111111111" \
--header "Content-Type: application/json" \
--data '{
"message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
"to": "did:openpayload:1111111111111111111111@example.com",
"tag": "Legal",
"timestamp": "<current-RFC3339-timestamp>",
"payload": {"ciphertext_b64":"<encrypted-message>"},
"encrypted_header": "<base64-encrypted-header>",
"header_nonce": "<base64-nonce>",
"header_key_id": "recipient-key-1",
"schema_version": "1"
}'
Response
The response is the sameDeliveryResult returned by Send an encrypted message.
Straight to the point
POST /relay/{url-encoded-recipient-did}
- Body base DID must equal path DID; aliases use
POST /relay - Persona stays in the body target; tag stays in the top-level
tagfield - Success and error schema:
DeliveryResult - Use
POST /relaywhen path binding provides no benefit