Desarrolladores

API de chats, correo y notificaciones

Estos endpoints cubren las herramientas de comunicación de Tylode: las conversaciones de chat, el correo interno (Correos) y tus notificaciones. Todo lo que envías con ellos sale en tu nombre, exactamente igual que si lo escribieras en la app.

Antes de empezar

URL base: https://app.tylode.com/api/v1
Manda tu token en la cabecera Authorization: Bearer tylode_pat_xxx. Los tokens de acceso personal necesitan el plan Pro. Consulta Autenticación.
Obtén el ID del espacio con GET /api/v1/workspaces o en la app, en Ajustes → Workspace → Datos del espacio → ID del espacio → Copiar.
Los errores que puede dar cualquier endpoint (401, 403, 429) se explican en Errores y convenciones.
Los ejemplos en JavaScript usan la función tylode() de la API de páginas.

Endpoints

Método	Ruta	Qué hace	Permiso (scope)
GET	`/api/v1/chats`	Lista tus conversaciones	`chats:read`
GET	`/api/v1/chats/:id/messages`	Lee los últimos mensajes de una conversación	`chats:read`
POST	`/api/v1/chats/:id/messages`	Envía un mensaje	`chats:write`
GET	`/api/v1/mail`	Lista tus hilos de correo	`mail:read`
POST	`/api/v1/mail`	Empieza un hilo de correo	`mail:write`
GET	`/api/v1/mail/:id`	Devuelve un hilo con sus mensajes	`mail:read`
POST	`/api/v1/mail/:id`	Responde en un hilo	`mail:write`
PATCH	`/api/v1/mail/:id`	Marca un hilo como leído/no leído o lo archiva	`mail:write`
GET	`/api/v1/notifications`	Lista tus notificaciones	`notifications:read`
POST	`/api/v1/notifications`	Marca todas tus notificaciones como leídas	`notifications:write`

Los permisos solo cuentan para las aplicaciones OAuth.

Dónde conseguir los IDs de usuario

Varios campos reciben o devuelven IDs de usuario: por ejemplo, mentions en los mensajes de chat y recipient_ids en el correo. No hay ningún endpoint que liste los miembros de un espacio ni que convierta un ID de usuario en un nombre o un email. Los IDs se recogen de otras respuestas:

Dónde	Campo
Mensajes de chat	`sender_id`, `mentions`
Conversaciones	`created_by`
Hilos y mensajes de correo	`created_by`, `sender_id`
Notificaciones	`actor_id` (quién la provocó), `recipient_id` (tú)
Pizarras, presentaciones	`created_by`, `owner_id`
Filas de bases de datos	valores de las columnas de tipo persona
Cargas de webhooks	`sender_id` (`message.created`), `user_id` (`member.joined`), `created_by` (`page.created`, `comment.created`)

Una forma práctica de montarte un directorio: lee los mensajes recientes de un chat de grupo en el que esté todo el mundo y asocia cada sender_id con la persona que sabes que lo escribió. Tu propio ID es el recipient_id de cualquiera de tus notificaciones, o el sender_id de un mensaje que hayas enviado.

Chats

Los chats son las conversaciones de Chats en la app: mensajes directos y grupos. Solo puedes leer y escribir en las conversaciones de las que formas parte. Mira Chats.

Listar conversaciones

GET /api/v1/chats

Devuelve las conversaciones en las que estás dentro de un espacio, de la creada más recientemente a la más antigua.

Permiso (scope): chats:read

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`workspace_id`	query	string	Sí	El espacio.

Cada conversación trae id, workspace_id, is_group (false en un mensaje directo), name (null en los mensajes directos), created_by, created_at y last_read_at (cuándo la leíste por última vez).

bash

curl "https://app.tylode.com/api/v1/chats?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer tylode_pat_xxx"

Respuesta 200

json

{
  "data": [
    {
      "id": "3c8a1e6f-9d2b-4f5a-a7e4-1b6c9d3f0e25",
      "workspace_id": "7c1e2a4b-3f5d-4e8a-9b21-6d0f5c8e1a37",
      "is_group": true,
      "name": "Marketing",
      "created_by": "6a1d8f3c-4e9b-4b2a-8c7f-5d0e2a9b1c63",
      "created_at": "2026-09-02T09:12:44.107512+00:00",
      "last_read_at": "2026-09-23T07:58:10.422091+00:00"
    },
    {
      "id": "8b3e6a1d-4c7f-4e2b-9d5a-0f3c6e9b2a74",
      "workspace_id": "7c1e2a4b-3f5d-4e8a-9b21-6d0f5c8e1a37",
      "is_group": false,
      "name": null,
      "created_by": "2f7c9e41-8b3a-4d6e-a1f5-0c8e3b7d9a52",
      "created_at": "2026-08-14T16:40:03.918377+00:00",
      "last_read_at": "2026-09-22T18:21:37.004218+00:00"
    }
  ]
}

Errores

Estado	Cuándo
`400`	Falta `workspace_id`.

No hay endpoint para crear conversaciones ni para añadir gente; eso se hace en la app.

Leer mensajes

GET /api/v1/chats/:id/messages

Devuelve los últimos mensajes de una conversación, en orden cronológico (el más antiguo del lote primero y el más reciente al final).

Permiso (scope): chats:read

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`id`	path	string	Sí	ID de la conversación.
`limit`	query	number	No	Cuántos de los últimos mensajes quieres, de 1 a 200. Por defecto, 50. Los valores fuera de rango se ajustan al límite más cercano.

Cada mensaje trae id, conversation_id, sender_id, body, attachment_id (null si no hay archivo), reply_to_message_id (el mensaje al que responde, o null), mentions (IDs de usuario) y created_at. No hay paginación: como mucho puedes leer los últimos 200 mensajes. Los archivos adjuntos no se pueden descargar por la API.

bash

curl "https://app.tylode.com/api/v1/chats/CONVERSATION_ID/messages?limit=20" \
  -H "Authorization: Bearer tylode_pat_xxx"

const messages = await tylode(`/chats/${CONVERSATION_ID}/messages?limit=20`);
const last = messages.at(-1); // el más reciente

Respuesta 200

json

{
  "data": [
    {
      "id": "d1a4c7e0-3f6b-4a9d-8c2e-5b8f1a4d7c09",
      "conversation_id": "3c8a1e6f-9d2b-4f5a-a7e4-1b6c9d3f0e25",
      "sender_id": "6a1d8f3c-4e9b-4b2a-8c7f-5d0e2a9b1c63",
      "body": "Who's reviewing the newsletter?",
      "attachment_id": null,
      "reply_to_message_id": null,
      "mentions": [],
      "created_at": "2026-09-23T08:02:15.771093+00:00"
    },
    {
      "id": "e2b5d8f1-4a7c-4b0e-9d3f-6c9a2b5e8d10",
      "conversation_id": "3c8a1e6f-9d2b-4f5a-a7e4-1b6c9d3f0e25",
      "sender_id": "2f7c9e41-8b3a-4d6e-a1f5-0c8e3b7d9a52",
      "body": "I'll do it. @Laura can you send me the final images?",
      "attachment_id": null,
      "reply_to_message_id": "d1a4c7e0-3f6b-4a9d-8c2e-5b8f1a4d7c09",
      "mentions": ["9e4b2c7a-1f6d-4a8e-b3c9-7a5f0d2e8b14"],
      "created_at": "2026-09-23T08:05:47.130256+00:00"
    }
  ]
}

Si no estás en la conversación, recibes una lista vacía, no un error.

Enviar un mensaje

POST /api/v1/chats/:id/messages

Publica un mensaje en una conversación de la que formas parte, en tu nombre.

Permiso (scope): chats:write

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`id`	path	string	Sí	ID de la conversación.
`body`	body	string	Sí	Texto del mensaje. No puede ir vacío ni ser solo espacios.
`reply_to_message_id`	body	string	No	ID de un mensaje de la misma conversación al que respondes.
`mentions`	body	array de strings	No	IDs de usuario a los que mencionas.

Cómo avisan las menciones y las respuestas:

Cada usuario de mentions recibe una notificación mention, si está en la conversación y no eres tú. Escribe el nombre en body tal como quieres que se lea (por ejemplo @Laura); lo que dispara la notificación es el array mentions.
Responder al mensaje de otra persona le manda una notificación reply, salvo que ya la hayas mencionado en el mismo mensaje.

bash

curl -X POST https://app.tylode.com/api/v1/chats/CONVERSATION_ID/messages \
  -H "Authorization: Bearer tylode_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "@Laura the build is green, ready to publish.",
    "mentions": ["9e4b2c7a-1f6d-4a8e-b3c9-7a5f0d2e8b14"]
  }'

const message = await tylode(`/chats/${CONVERSATION_ID}/messages`, {
  method: "POST",
  body: {
    body: "@Laura the build is green, ready to publish.",
    mentions: ["9e4b2c7a-1f6d-4a8e-b3c9-7a5f0d2e8b14"],
  },
});

Respuesta 201

json

{
  "data": {
    "id": "f3c6e9a2-5b8d-4c1f-a0e4-7d0b3c6f9e21",
    "conversation_id": "3c8a1e6f-9d2b-4f5a-a7e4-1b6c9d3f0e25",
    "sender_id": "2f7c9e41-8b3a-4d6e-a1f5-0c8e3b7d9a52",
    "body": "@Laura the build is green, ready to publish.",
    "attachment_id": null,
    "reply_to_message_id": null,
    "mentions": ["9e4b2c7a-1f6d-4a8e-b3c9-7a5f0d2e8b14"],
    "created_at": "2026-09-23T10:14:02.583917+00:00"
  }
}

Errores

Estado	Cuándo
`400`	Falta `body` o está en blanco.
`400`	No se ha podido enviar el mensaje (por ejemplo, porque no estás en esa conversación).

Los mensajes de los chats de grupo disparan el evento de webhook message.created; los mensajes directos, nunca.

Correo

El correo es el correo interno de Tylode entre personas, el de Correos; no es email. Cada persona tiene su propio estado de leído y archivado en cada hilo. Mira Correos.

Listar hilos de correo

GET /api/v1/mail

Devuelve los hilos en los que participas y que se empezaron en un espacio, del actualizado más recientemente al más antiguo.

Permiso (scope): mail:read

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`workspace_id`	query	string	Sí	Espacio en el que se empezaron los hilos.
`archived`	query	string	No	Sin él, la bandeja de entrada (lo no archivado). `true` para solo lo archivado; `all` para todo.

Cada hilo trae id, workspace_id, subject, created_by, created_at, updated_at y tu propio is_read y archived.

bash

curl "https://app.tylode.com/api/v1/mail?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer tylode_pat_xxx"

const unread = (await tylode(`/mail?workspace_id=${WORKSPACE_ID}`)).filter((t) => !t.is_read);

Respuesta 200

json

{
  "data": [
    {
      "id": "4d9b2e7a-0c5f-4a3d-b8e1-6f2a9c4e7b35",
      "workspace_id": "7c1e2a4b-3f5d-4e8a-9b21-6d0f5c8e1a37",
      "subject": "Holiday calendar 2027",
      "created_by": "6a1d8f3c-4e9b-4b2a-8c7f-5d0e2a9b1c63",
      "created_at": "2026-09-22T11:30:18.264850+00:00",
      "updated_at": "2026-09-23T09:02:51.019734+00:00",
      "is_read": false,
      "archived": false
    }
  ]
}

Errores

Estado	Cuándo
`400`	Falta `workspace_id`.

Empezar un hilo de correo

POST /api/v1/mail

Crea un hilo con su primer mensaje y se lo envía a los destinatarios.

Permiso (scope): mail:write

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`workspace_id`	body	string	Sí	Espacio desde el que se empieza el hilo.
`subject`	body	string	Sí	Asunto. No puede ir en blanco.
`body`	body	string	Sí	Primer mensaje. No puede ir en blanco.
`recipient_ids`	body	array de strings	Sí	IDs de usuario de los destinatarios, al menos uno. Mira Dónde conseguir los IDs de usuario.

Tú entras en el hilo automáticamente, marcado como leído; cada destinatario lo recibe sin leer.

bash

curl -X POST https://app.tylode.com/api/v1/mail \
  -H "Authorization: Bearer tylode_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "subject": "Weekly report",
    "body": "Hi both, this week we closed 14 tickets and shipped the new onboarding.",
    "recipient_ids": ["6a1d8f3c-4e9b-4b2a-8c7f-5d0e2a9b1c63", "9e4b2c7a-1f6d-4a8e-b3c9-7a5f0d2e8b14"]
  }'

const thread = await tylode("/mail", {
  method: "POST",
  body: {
    workspace_id: WORKSPACE_ID,
    subject: "Weekly report",
    body: "Hi both, this week we closed 14 tickets and shipped the new onboarding.",
    recipient_ids: [MARC_ID, LAURA_ID],
  },
});

Respuesta 201

json

{
  "data": {
    "id": "5e0c3f8b-1d6a-4b4e-a9f2-7a3b0d5f8c46",
    "workspace_id": "7c1e2a4b-3f5d-4e8a-9b21-6d0f5c8e1a37",
    "subject": "Weekly report",
    "created_by": "2f7c9e41-8b3a-4d6e-a1f5-0c8e3b7d9a52",
    "created_at": "2026-09-23T10:20:07.441285+00:00",
    "updated_at": "2026-09-23T10:20:07.441285+00:00",
    "messages": [
      {
        "id": "6f1d4a9c-2e7b-4c5f-b0a3-8b4c1e6a9d57",
        "thread_id": "5e0c3f8b-1d6a-4b4e-a9f2-7a3b0d5f8c46",
        "sender_id": "2f7c9e41-8b3a-4d6e-a1f5-0c8e3b7d9a52",
        "body": "Hi both, this week we closed 14 tickets and shipped the new onboarding.",
        "attachment_id": null,
        "created_at": "2026-09-23T10:20:07.583102+00:00"
      }
    ]
  }
}

Errores

Estado	Cuándo
`400`	Falta `workspace_id`, `subject` o `body`, o van en blanco.
`400`	Falta `recipient_ids` o está vacío.
`400`	No se ha podido crear el hilo. No queda nada enviado a medias.

Obtener un hilo de correo

GET /api/v1/mail/:id

Devuelve un hilo con todos sus mensajes, del más antiguo al más reciente.

Permiso (scope): mail:read

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`id`	path	string	Sí	ID del hilo.

El hilo trae id, workspace_id, subject, created_by, created_at, updated_at y messages. Cada mensaje trae id, thread_id, sender_id, body, attachment_id y created_at. Leer un hilo no lo marca como leído; para eso usa PATCH.

bash

curl https://app.tylode.com/api/v1/mail/THREAD_ID \
  -H "Authorization: Bearer tylode_pat_xxx"

Respuesta 200

json

{
  "data": {
    "id": "4d9b2e7a-0c5f-4a3d-b8e1-6f2a9c4e7b35",
    "workspace_id": "7c1e2a4b-3f5d-4e8a-9b21-6d0f5c8e1a37",
    "subject": "Holiday calendar 2027",
    "created_by": "6a1d8f3c-4e9b-4b2a-8c7f-5d0e2a9b1c63",
    "created_at": "2026-09-22T11:30:18.264850+00:00",
    "updated_at": "2026-09-23T09:02:51.019734+00:00",
    "messages": [
      {
        "id": "7a2e5b0d-3f8c-4d6a-a1b4-9c5d2f7b0e68",
        "thread_id": "4d9b2e7a-0c5f-4a3d-b8e1-6f2a9c4e7b35",
        "sender_id": "6a1d8f3c-4e9b-4b2a-8c7f-5d0e2a9b1c63",
        "body": "Please add your days off before Friday.",
        "attachment_id": null,
        "created_at": "2026-09-22T11:30:18.402117+00:00"
      }
    ]
  }
}

Errores

Estado	Cuándo
`404`	El hilo no existe o no participas en él.

Responder en un hilo

POST /api/v1/mail/:id

Añade tu respuesta a un hilo en el que participas.

Permiso (scope): mail:write

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`id`	path	string	Sí	ID del hilo.
`body`	body	string	Sí	Texto de la respuesta. No puede ir en blanco.

bash

curl -X POST https://app.tylode.com/api/v1/mail/THREAD_ID \
  -H "Authorization: Bearer tylode_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Done, I have added mine." }'

Respuesta 201

json

{
  "data": {
    "id": "8b3f6c1e-4a9d-4e7b-b2c5-0d6e3a8c1f79",
    "thread_id": "4d9b2e7a-0c5f-4a3d-b8e1-6f2a9c4e7b35",
    "sender_id": "2f7c9e41-8b3a-4d6e-a1f5-0c8e3b7d9a52",
    "body": "Done, I have added mine.",
    "attachment_id": null,
    "created_at": "2026-09-23T10:31:44.896520+00:00"
  }
}

Errores

Estado	Cuándo
`400`	Falta `body` o está en blanco.
`400`	No se ha podido guardar la respuesta (por ejemplo, porque no participas en ese hilo).

Marcar un hilo como leído o archivado

PATCH /api/v1/mail/:id

Cambia tu propio estado en un hilo: leído o no leído, archivado o en la bandeja de entrada. Al resto de participantes no les afecta. En el servidor MCP, es la herramienta update_mail_thread.

Permiso (scope): mail:write

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`id`	path	string	Sí	ID del hilo.
`is_read`	body	boolean	No*	`true` para marcarlo como leído, `false` como no leído.
`archived`	body	boolean	No*	`true` para archivarlo, `false` para devolverlo a la bandeja de entrada.

* Manda al menos uno, como booleano de verdad (true, no "true").

bash

curl -X PATCH https://app.tylode.com/api/v1/mail/THREAD_ID \
  -H "Authorization: Bearer tylode_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "is_read": true, "archived": true }'

Respuesta 200

La respuesta repite lo que has cambiado:

json

{
  "data": {
    "thread_id": "4d9b2e7a-0c5f-4a3d-b8e1-6f2a9c4e7b35",
    "is_read": true,
    "archived": true
  }
}

Errores

Estado	Cuándo
`400`	No se ha mandado ni `is_read` ni `archived` como booleano.

Notificaciones

Las notificaciones son las de Actividad: menciones, respuestas, tarjetas que te asignan y páginas que comparten contigo. Mira Notificaciones.

Listar notificaciones

GET /api/v1/notifications

Devuelve tus notificaciones en un espacio, de la más reciente a la más antigua. Por defecto, solo las no leídas.

Permiso (scope): notifications:read

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`workspace_id`	query	string	Sí	El espacio.
`include_read`	query	string	No	`true` para incluir también las que ya has leído.

Recibes como mucho las 100 notificaciones más recientes. Cada una trae:

Campo	Descripción
`id`	ID de la notificación.
`recipient_id`	Tú.
`workspace_id`	El espacio.
`actor_id`	Quién la provocó, o `null` si esa cuenta ya no existe.
`kind`	`mention`, `reply`, `card_assigned` o `page_shared`.
`target_type`	A qué apunta: `message`, `voice_message`, `card` o `page`.
`target_id`	ID de ese mensaje, mensaje de canal de voz, tarjeta o página.
`context_id`	Dónde está el destino: la conversación para `message`, el canal de voz para `voice_message` y `null` en el resto.
`preview`	Un extracto corto (hasta 140 caracteres): el texto del mensaje, el título de la tarjeta o el de la página.
`read_at`	Cuándo la leíste, o `null`.
`created_at`	Cuándo se creó.

bash

curl "https://app.tylode.com/api/v1/notifications?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer tylode_pat_xxx"

const pending = await tylode(`/notifications?workspace_id=${WORKSPACE_ID}`);
const mentions = pending.filter((n) => n.kind === "mention");

Respuesta 200

json

{
  "data": [
    {
      "id": "9c4a7d2f-5b0e-4f8c-a3d6-1e7b4c9f2a80",
      "recipient_id": "2f7c9e41-8b3a-4d6e-a1f5-0c8e3b7d9a52",
      "workspace_id": "7c1e2a4b-3f5d-4e8a-9b21-6d0f5c8e1a37",
      "actor_id": "9e4b2c7a-1f6d-4a8e-b3c9-7a5f0d2e8b14",
      "kind": "mention",
      "target_type": "message",
      "target_id": "0d5b8e3a-6c1f-4a9d-b4e7-2f8c5d0a3b91",
      "context_id": "3c8a1e6f-9d2b-4f5a-a7e4-1b6c9d3f0e25",
      "preview": "@Ana the final images are in the shared folder",
      "read_at": null,
      "created_at": "2026-09-23T10:40:12.338461+00:00"
    },
    {
      "id": "a0d5b8e3-6c1f-4a9d-b4e7-2f8c5d0a3b92",
      "recipient_id": "2f7c9e41-8b3a-4d6e-a1f5-0c8e3b7d9a52",
      "workspace_id": "7c1e2a4b-3f5d-4e8a-9b21-6d0f5c8e1a37",
      "actor_id": "6a1d8f3c-4e9b-4b2a-8c7f-5d0e2a9b1c63",
      "kind": "card_assigned",
      "target_type": "card",
      "target_id": "c4f7a0d3-6b9e-4c2f-8a5d-1e4b7c0f3a96",
      "context_id": null,
      "preview": "Fix the signup email",
      "read_at": null,
      "created_at": "2026-09-23T09:15:40.702583+00:00"
    }
  ]
}

Errores

Estado	Cuándo
`400`	Falta `workspace_id`.

Marcar todas las notificaciones como leídas

POST /api/v1/notifications

Marca como leídas todas tus notificaciones sin leer de un espacio y te dice cuántas eran. No hay endpoint para marcar una sola.

Permiso (scope): notifications:write

Parámetro	Dónde	Tipo	Obligatorio	Descripción
`workspace_id`	body	string	Sí	El espacio.

bash

curl -X POST https://app.tylode.com/api/v1/notifications \
  -H "Authorization: Bearer tylode_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_id": "WORKSPACE_ID" }'

Respuesta 200

json

{
  "data": { "marked": 2 }
}

Errores

Estado	Cuándo
`400`	Falta `workspace_id` o no se han podido actualizar las notificaciones.

Relacionado

Chats, Correos y Notificaciones en la app
Webhooks, para reaccionar al momento a los mensajes nuevos de los chats de grupo
API de búsqueda, que también encuentra hilos de correo y mensajes de chat
MCP, para que un asistente lea y conteste tus mensajes

API de chats, correo y notificaciones

#Antes de empezar

#Endpoints

#Dónde conseguir los IDs de usuario

#Chats

#Listar conversaciones

#Leer mensajes

#Enviar un mensaje

#Correo

#Listar hilos de correo

#Empezar un hilo de correo

#Obtener un hilo de correo

#Responder en un hilo

#Marcar un hilo como leído o archivado

#Notificaciones

#Listar notificaciones

#Marcar todas las notificaciones como leídas

#Relacionado

Antes de empezar

Endpoints

Dónde conseguir los IDs de usuario

Chats

Listar conversaciones

Leer mensajes

Enviar un mensaje

Correo

Listar hilos de correo

Empezar un hilo de correo

Obtener un hilo de correo

Responder en un hilo

Marcar un hilo como leído o archivado

Notificaciones

Listar notificaciones

Marcar todas las notificaciones como leídas

Relacionado