> ## 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.

# Send an encrypted message

> Submit a DDN envelope to a Relay using the recipient declared in the envelope

Use this endpoint after your client has resolved the recipient, encrypted the message, and built a DDN envelope. The Relay reads only the public outer fields needed for validation and delivery.

## Request

The body is one JSON [DDN envelope](/guides/ddn-envelope).

<ParamField body="message_id" type="string" required>
  A UUID generated once for this message. Reusing it may cause deduplication.
</ParamField>

<ParamField body="to" type="string" required>
  The recipient Talaria DID. `recipient` is accepted as an alternate field name.
</ParamField>

<ParamField body="timestamp" type="string" required>
  ISO-8601, epoch milliseconds, or epoch seconds. `created_at` is accepted as an alternate.
</ParamField>

<ParamField body="payload" type="object" required>
  Your encrypted application payload.
</ParamField>

<ParamField body="encrypted_header" type="string">
  Base64 encrypted header. When used, also send `header_nonce`, `schema_version`, and a header key reference.
</ParamField>

<ParamField body="context" type="object">
  Alternate compact encrypted-header object. Provide this or the flat encrypted-header fields.
</ParamField>

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url "https://relay.example.com/relay" \
    --header "Content-Type: application/json" \
    --data '{
      "message_id": "9f8d6f08-bce5-4df5-b22b-bf8c6bd4e143",
      "to": "did:talaria:1111111111111111111111",
      "timestamp": "2026-07-24T16:30:00Z",
      "ttl": "24h",
      "delivery_hint": "standard",
      "payload": {
        "ciphertext_b64": "<encrypted-message>"
      },
      "encrypted_header": "<base64-encrypted-header>",
      "header_nonce": "<base64-nonce>",
      "header_key_id": "recipient-key-1",
      "schema_version": "1"
    }'
  ```
</RequestExample>

## Response

<ResponseField name="success" type="boolean" required>
  Whether the Relay completed the reported delivery mode.
</ResponseField>

<ResponseField name="delivery_mode" type="string" required>
  The successful mode or `failed`.
</ResponseField>

<ResponseField name="http_status" type="integer" required>
  The HTTP status represented by the result.
</ResponseField>

<ResponseField name="code" type="string" required>
  A stable machine-readable result code.
</ResponseField>

<ResponseField name="retry_count" type="integer" required>
  Retries performed by this delivery attempt.
</ResponseField>

<ResponseField name="cache_attempted" type="boolean" required>
  Whether the Relay attempted Cache fallback.
</ResponseField>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "success": true,
    "delivery_mode": "direct",
    "http_status": 200,
    "code": "delivered",
    "message": "Envelope delivered",
    "retry_count": 0,
    "cache_attempted": false,
    "cache_result": null,
    "ndr": null,
    "details": {}
  }
  ```
</ResponseExample>

## Common failures

| Status      | Meaning                                                                                         |
| ----------- | ----------------------------------------------------------------------------------------------- |
| `400`       | Invalid JSON, missing field, unknown field, malformed DID, UUID, TTL, header, or chunk metadata |
| `403`       | A supplied sender signature or recipient policy check failed                                    |
| `404`       | Recipient or required public service information was not found                                  |
| `413`       | Envelope, header, payload, or chunk exceeds the node's advertised limit                         |
| `422`       | Message or recipient state is not deliverable                                                   |
| `429`       | Relay is rate-limiting requests                                                                 |
| `502`/`503` | An upstream destination or required service is unavailable                                      |

## Straight to the point

```http theme={null}
POST /relay
Content-Type: application/json

<DDN envelope whose to field contains the recipient DID>
```