Send an encrypted message - Talaria Developer Documentation

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"
  }'

{
  "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": {}
}

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"
  }'

{
  "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": {}
}

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.

string

required

A UUID generated once for this message. Reusing it may cause deduplication.

string

required

The recipient Talaria DID. recipient is accepted as an alternate field name.

string

required

ISO-8601, epoch milliseconds, or epoch seconds. created_at is accepted as an alternate.

object

required

Your encrypted application payload.

string

Base64 encrypted header. When used, also send header_nonce, schema_version, and a header key reference.

object

Alternate compact encrypted-header object. Provide this or the flat encrypted-header fields.

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"
  }'

Response

boolean

required

Whether the Relay completed the reported delivery mode.

string

required

The successful mode or failed.

integer

required

The HTTP status represented by the result.

string

required

A stable machine-readable result code.

integer

required

Retries performed by this delivery attempt.

boolean

required

Whether the Relay attempted Cache fallback.

{
  "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": {}
}

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

POST /relay
Content-Type: application/json

<DDN envelope whose to field contains the recipient DID>

Talaria Relay API Send to a path-bound recipient

⌘I

​Request

​Response

​Common failures

​Straight to the point

Request

Response

Common failures

Straight to the point