Lydira API
TR

API reference

Communications

4 endpoints

The unified inbox: email, SMS, WhatsApp and internal notes against a customer or a trip. Sending is asynchronous. A POST with an outbound direction on a deliverable channel returns the queued row immediately and the transport runs after; poll status / sent_at / failed_at, or subscribe to the record webhooks.

Message bodies are PII. A role without that permission sees content_masked: true with subject, preview and both body fields null.

List messages

GET/api/v1/communications

Needs a key with the full scope.

Newest first, across every channel. unread_count is the account-wide figure for the key's principal and is returned beside the page, so a badge needs no second call.

Parameters

Query

  • qstring
  • customer_iduuid
  • trip_iduuid
  • channelstring
  • directionenum

    one ofinboundoutboundinternal

  • thread_idstring

    Returns the whole conversation.

  • scopeenum

    one ofunread

  • limitintegerdefault 25

    Rows per page.

  • cursorstring

    Opaque; take it from the previous response's page.next_cursor.

Response · 200

  • dataobject[]required
    Show fields
    • iduuid
    • customer_iduuidnullable
    • trip_iduuidnullable
    • directionenum

      one ofinboundoutboundinternal

    • channelstring
    • statusstringnullable
    • subjectstringnullable
    • previewstringnullable

      First 160 characters of the plain body.

    • content_maskedboolean

      True when the role cannot read message content. subject, preview and both bodies are then null.

    • from_addressstringnullable
    • to_addressesstring[]
    • thread_idstringnullable
    • sent_atdate-timenullable
    • delivered_atdate-timenullable
    • read_atdate-timenullable
    • created_atdate-time
    • unreadboolean
  • pageobjectrequired

    The cursor for the list beside it. Re-send the same request with ?cursor=<next_cursor> while has_more is true. next_cursor is null on the last page.

    Show fields
    • next_cursorstringrequirednullable
    • has_morebooleanrequired
    • limitintegerrequired
  • unread_countintegerrequired

Responses

  • 401Missing or invalid Bearer token
  • 403Policy denied or account has no owner
  • 429Rate limit exceeded
curl -X GET 'https://YOUR-CELL.lydira.com/api/v1/communications' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY'
Response
200
{
  "data": [
    {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "direction": "inbound",
      "channel": "email",
      "status": "confirmed",
      "subject": "Confirm the hotel allocation",
      "preview": "Hello Ayşe, your itinerary is attached.",
      "content_masked": true,
      "from_address": "operations@agency.example",
      "to_addresses": [
        "ayse@example.com"
      ],
      "thread_id": "thr_8f14e45fea2c",
      "sent_at": "2026-03-14T09:30:00Z",
      "delivered_at": "2026-03-14T09:30:00Z",
      "read_at": "2026-03-14T09:30:00Z",
      "created_at": "2026-03-14T09:30:00Z",
      "unread": true
    }
  ],
  "page": {
    "next_cursor": "MjAyNi0wMy0xNFQwOTozMDowMC4wMDAwMDBafDk0MQ",
    "has_more": true,
    "limit": 25
  },
  "unread_count": 3
}

Send or log a message

POST/api/v1/communications

Needs a key with the full scope.

Two jobs in one endpoint, told apart by direction.

outbound on email, sms or whatsapp queues a real send. The response comes back before the transport runs, so the row you get is the queued one: watch status, sent_at and failed_at to learn the outcome. internal (the default when direction is omitted) records a note against the customer or trip and sends nothing. inbound files a message your own system received.

Reply by carrying the parent's thread_id and setting in_reply_to.

Parameters

Headers

  • Idempotency-Keystring

    Your own unique string for this write (a UUID is the obvious choice), max 255 characters. Optional: omit it and nothing changes. Send it and a repeat of the same request returns this call's response verbatim, with Idempotent-Replay: true, instead of writing again.

Body

  • communicationobjectrequired
    Show fields
    • directionenumdefault internal

      outbound on a deliverable channel queues a real send.

      one ofinboundoutboundinternal

    • channelstring

      email, sms and whatsapp are deliverable.

    • customer_iduuid
    • trip_iduuid
    • company_iduuid
    • subjectstring
    • body_plainstring
    • body_htmlstring
    • from_addressstring
    • reply_tostring
    • in_reply_tostring
    • thread_idstring

      Carry the parent's value to keep a reply in its conversation.

    • external_idstring
    • to_addressesstring[]
    • cc_addressesstring[]

Response · 201

  • dataobject
    Show fields
    • iduuid
    • customer_iduuidnullable
    • trip_iduuidnullable
    • directionenum

      one ofinboundoutboundinternal

    • channelstring
    • statusstringnullable
    • subjectstringnullable
    • previewstringnullable

      First 160 characters of the plain body.

    • content_maskedboolean

      True when the role cannot read message content. subject, preview and both bodies are then null.

    • from_addressstringnullable
    • to_addressesstring[]
    • thread_idstringnullable
    • sent_atdate-timenullable
    • delivered_atdate-timenullable
    • read_atdate-timenullable
    • created_atdate-time
    • unreadboolean
    • body_plainstringnullable
    • body_htmlstringnullable
    • cc_addressesstring[]
    • reply_tostringnullable
    • in_reply_tostringnullable
    • external_idstringnullable

      The provider's own id for the message.

    • failed_atdate-timenullable
    • failure_reasonstringnullable
    • metadataobjectnullable
    • authorobjectnullable

      A seat on the account, as referenced from other records.

      Show fields
      • iduuid
      • namestringnullable
      • emailstringnullable
    • customerobjectnullable
      Show fields
      • iduuid
      • namestringnullable
    • tripobjectnullable
      Show fields
      • iduuid
      • titlestring
    • updated_atdate-time

Responses

  • 401Missing or invalid Bearer token
  • 403Policy denied or account has no owner
  • 422The request was understood but the record could not be written. details maps each rejected attribute to its reasons, so a client can put the message next to the field that caused it.
  • 429Rate limit exceeded
curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/communications' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "communication": {
    "channel": "email",
    "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "subject": "Your Cappadocia itinerary",
    "body_plain": "Hello Ayşe, your itinerary is attached.",
    "to_addresses": [
      "ayse@example.com"
    ]
  }
}'
Response
201
{
  "data": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "direction": "inbound",
    "channel": "email",
    "status": "confirmed",
    "subject": "Confirm the hotel allocation",
    "preview": "Hello Ayşe, your itinerary is attached.",
    "content_masked": true,
    "from_address": "operations@agency.example",
    "to_addresses": [
      "ayse@example.com"
    ],
    "thread_id": "thr_8f14e45fea2c",
    "sent_at": "2026-03-14T09:30:00Z",
    "delivered_at": "2026-03-14T09:30:00Z",
    "read_at": "2026-03-14T09:30:00Z",
    "created_at": "2026-03-14T09:30:00Z",
    "unread": true,
    "body_plain": "Hello Ayşe, your itinerary is attached.",
    "body_html": "<p>Hello Ayşe, your itinerary is attached.</p>",
    "cc_addresses": [
      "accounts@agency.example"
    ],
    "reply_to": "operations@agency.example",
    "in_reply_to": "<message-id@example.com>",
    "external_id": "CRM-88213",
    "failed_at": "2026-03-14T09:30:00Z",
    "failure_reason": "string",
    "metadata": {},
    "author": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com"
    },
    "customer": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz"
    },
    "trip": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "title": "Cappadocia, 4 nights"
    },
    "updated_at": "2026-03-14T09:30:00Z"
  }
}

Read a message

GET/api/v1/communications/{id}

Needs a key with the full scope.

Adds the full body, the recipient lists and the linked customer and trip.

Parameters

Path

  • iduuidrequired

Response · 200

  • dataobject
    Show fields
    • iduuid
    • customer_iduuidnullable
    • trip_iduuidnullable
    • directionenum

      one ofinboundoutboundinternal

    • channelstring
    • statusstringnullable
    • subjectstringnullable
    • previewstringnullable

      First 160 characters of the plain body.

    • content_maskedboolean

      True when the role cannot read message content. subject, preview and both bodies are then null.

    • from_addressstringnullable
    • to_addressesstring[]
    • thread_idstringnullable
    • sent_atdate-timenullable
    • delivered_atdate-timenullable
    • read_atdate-timenullable
    • created_atdate-time
    • unreadboolean
    • body_plainstringnullable
    • body_htmlstringnullable
    • cc_addressesstring[]
    • reply_tostringnullable
    • in_reply_tostringnullable
    • external_idstringnullable

      The provider's own id for the message.

    • failed_atdate-timenullable
    • failure_reasonstringnullable
    • metadataobjectnullable
    • authorobjectnullable

      A seat on the account, as referenced from other records.

      Show fields
      • iduuid
      • namestringnullable
      • emailstringnullable
    • customerobjectnullable
      Show fields
      • iduuid
      • namestringnullable
    • tripobjectnullable
      Show fields
      • iduuid
      • titlestring
    • updated_atdate-time

Responses

  • 401Missing or invalid Bearer token
  • 403Policy denied or account has no owner
  • 404Resource not found
  • 429Rate limit exceeded
curl -X GET 'https://YOUR-CELL.lydira.com/api/v1/communications/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY'
Response
200
{
  "data": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "direction": "inbound",
    "channel": "email",
    "status": "confirmed",
    "subject": "Confirm the hotel allocation",
    "preview": "Hello Ayşe, your itinerary is attached.",
    "content_masked": true,
    "from_address": "operations@agency.example",
    "to_addresses": [
      "ayse@example.com"
    ],
    "thread_id": "thr_8f14e45fea2c",
    "sent_at": "2026-03-14T09:30:00Z",
    "delivered_at": "2026-03-14T09:30:00Z",
    "read_at": "2026-03-14T09:30:00Z",
    "created_at": "2026-03-14T09:30:00Z",
    "unread": true,
    "body_plain": "Hello Ayşe, your itinerary is attached.",
    "body_html": "<p>Hello Ayşe, your itinerary is attached.</p>",
    "cc_addresses": [
      "accounts@agency.example"
    ],
    "reply_to": "operations@agency.example",
    "in_reply_to": "<message-id@example.com>",
    "external_id": "CRM-88213",
    "failed_at": "2026-03-14T09:30:00Z",
    "failure_reason": "string",
    "metadata": {},
    "author": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com"
    },
    "customer": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz"
    },
    "trip": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "title": "Cappadocia, 4 nights"
    },
    "updated_at": "2026-03-14T09:30:00Z"
  }
}

Mark a message read

POST/api/v1/communications/{id}/mark_read

Needs a key with the full scope.

Parameters

Path

  • iduuidrequired

Headers

  • Idempotency-Keystring

    Your own unique string for this write (a UUID is the obvious choice), max 255 characters. Optional: omit it and nothing changes. Send it and a repeat of the same request returns this call's response verbatim, with Idempotent-Replay: true, instead of writing again.

Response · 200

  • dataobjectrequired
    Show fields
    • iduuid
    • customer_iduuidnullable
    • trip_iduuidnullable
    • directionenum

      one ofinboundoutboundinternal

    • channelstring
    • statusstringnullable
    • subjectstringnullable
    • previewstringnullable

      First 160 characters of the plain body.

    • content_maskedboolean

      True when the role cannot read message content. subject, preview and both bodies are then null.

    • from_addressstringnullable
    • to_addressesstring[]
    • thread_idstringnullable
    • sent_atdate-timenullable
    • delivered_atdate-timenullable
    • read_atdate-timenullable
    • created_atdate-time
    • unreadboolean
    • body_plainstringnullable
    • body_htmlstringnullable
    • cc_addressesstring[]
    • reply_tostringnullable
    • in_reply_tostringnullable
    • external_idstringnullable

      The provider's own id for the message.

    • failed_atdate-timenullable
    • failure_reasonstringnullable
    • metadataobjectnullable
    • authorobjectnullable

      A seat on the account, as referenced from other records.

      Show fields
      • iduuid
      • namestringnullable
      • emailstringnullable
    • customerobjectnullable
      Show fields
      • iduuid
      • namestringnullable
    • tripobjectnullable
      Show fields
      • iduuid
      • titlestring
    • updated_atdate-time
  • unread_countintegerrequired

Responses

  • 401Missing or invalid Bearer token
  • 403Policy denied or account has no owner
  • 404Resource not found
  • 429Rate limit exceeded
curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/communications/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/mark_read' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90'
Response
200
{
  "data": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "direction": "inbound",
    "channel": "email",
    "status": "confirmed",
    "subject": "Confirm the hotel allocation",
    "preview": "Hello Ayşe, your itinerary is attached.",
    "content_masked": true,
    "from_address": "operations@agency.example",
    "to_addresses": [
      "ayse@example.com"
    ],
    "thread_id": "thr_8f14e45fea2c",
    "sent_at": "2026-03-14T09:30:00Z",
    "delivered_at": "2026-03-14T09:30:00Z",
    "read_at": "2026-03-14T09:30:00Z",
    "created_at": "2026-03-14T09:30:00Z",
    "unread": true,
    "body_plain": "Hello Ayşe, your itinerary is attached.",
    "body_html": "<p>Hello Ayşe, your itinerary is attached.</p>",
    "cc_addresses": [
      "accounts@agency.example"
    ],
    "reply_to": "operations@agency.example",
    "in_reply_to": "<message-id@example.com>",
    "external_id": "CRM-88213",
    "failed_at": "2026-03-14T09:30:00Z",
    "failure_reason": "string",
    "metadata": {},
    "author": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com"
    },
    "customer": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz"
    },
    "trip": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "title": "Cappadocia, 4 nights"
    },
    "updated_at": "2026-03-14T09:30:00Z"
  },
  "unread_count": 3
}