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

# Talaria 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 Talaria DID
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

## Which endpoint should I use?

| Endpoint                     | Use it when                                                           |
| ---------------------------- | --------------------------------------------------------------------- |
| `POST /relay`                | The envelope's `to` or `recipient` field is the only recipient source |
| `POST /relay/{recipientDid}` | You also want the URL to bind the request to one recipient            |

Both routes call the same delivery service. On the path form, the path DID and envelope recipient must agree.

## What success means

The Relay returns a `DeliveryResult`. Success means the Relay completed the delivery mode reported in that result. Failure responses can describe direct-delivery failure, Cache fallback, retries, and a non-delivery receipt without revealing plaintext message contents.

<Warning>
  Encrypt the header and payload before submission. A Relay endpoint is not an encryption service.
</Warning>

## 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}
```