Bandeja de entrada

La API de Inbox expone la bandeja de entrada unificada de graph8 para email, SMS y LinkedIn (HeyReach) en una sola estructura de hilo. Úsela para integrar respuestas y asignaciones en su propia interfaz, o para potenciar agentes de IA que clasifiquen mensajes entrantes.

El parámetro de consulta o campo de solicitud channel siempre utiliza los valores orientados al desarrollador:

Valor de canal	Canal interno
`email`	email
`sms`	sms
`linkedin`	heyreach

Los hilos del canal LinkedIn devuelven channel: "linkedin" en las respuestas.

Endpoint	Método	Descripción
`/inbox`	GET	Listar hilos de todos los canales
`/inbox/{reply_id}`	GET	Obtener un hilo individual
`/inbox/{reply_id}/assign`	POST	Asignar un usuario a un hilo
`/inbox/{reply_id}/tag`	POST	Agregar etiquetas a un hilo
`/inbox/{reply_id}/draft`	GET	Generar un borrador con IA (consume créditos)
`/inbox/{reply_id}/send`	POST	Enviar una respuesta en un canal

Para consultar los esquemas en formato legible por máquina, vea la documentación interactiva de la API.

Listar hilos de la bandeja de entrada

GET /inbox

Devuelve hilos paginados de todos los canales (o de un canal específico mediante filtro).

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`channel`	string	-	`email`, `sms` o `linkedin`. Omitir para todos
`sequence_id`	string	-	Filtrar por ID de secuencia (campaña)
`status`	string	-	Filtrar por estado del hilo
`assignee`	string	-	Filtrar hilos asignados a este email
`tag`	string	-	Filtrar por ID de etiqueta
`page`	integer	1	Número de página (>= 1)
`page_size`	integer	50	1-100

curl "https://be.graph8.com/api/v1/inbox?channel=email&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/inbox",
    headers=HEADERS,
    params={"channel": "email", "page_size": 20},
)
threads = response.json()["data"]

Respuesta

{
  "data": [
    {
      "id": "thr_abc123",
      "channel": "email",
      "subject": "Re: Q2 outbound",
      "contact": {"email": "[email protected]", "name": "Jane Smith"},
      "messages": [
        {
          "message_id": "msg_001",
          "from_address": "[email protected]",
          "to_addresses": ["[email protected]"],
          "content": "Sounds great - let's chat Tuesday.",
          "responder": "OTHER",
          "date": "2026-04-15T14:30:00Z",
          "is_draft": false
        }
      ],
      "status": "open",
      "tags": [{"id": "tag_1", "name": "interested"}],
      "assignees": [{"email": "[email protected]", "name": "Sales Rep"}],
      "created_at": "2026-04-15T14:30:00Z",
      "updated_at": "2026-04-15T14:30:00Z"
    }
  ],
  "pagination": {"page": 1, "limit": 20, "total": 1, "has_next": false}
}

El campo responder de un mensaje toma los valores USER (un usuario de graph8 respondió), AI (graph8 envió una respuesta generada por IA) u OTHER (el contacto). El campo status puede ser open, responded o ai_responded.

Obtener hilo

GET /inbox/{reply_id}

Devuelve un hilo según su ID. Pase el parámetro de consulta channel correspondiente para que se consulte el almacén de datos correcto.

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`channel`	string	`email`	`email`, `sms` o `linkedin`

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/inbox/thr_abc123?channel=email" \
  -H "Authorization: Bearer $API_KEY"

Errores

Estado	Significado
`400`	`reply_id` inválido (nulo, indefinido o vacío se rechaza de forma temprana)

Asignar respuesta

POST /inbox/{reply_id}/assign

Asigna un usuario al hilo mediante su email.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`assignee_email`	string	Sí	Email del usuario que se va a asignar

Ejemplo

cURL

curl -X POST "https://be.graph8.com/api/v1/inbox/thr_abc123/assign?channel=email" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignee_email": "[email protected]"}'

Respuesta

{ "data": { "assigned": true, "assignee": "[email protected]", "count": 1 } }

Etiquetar respuesta

POST /inbox/{reply_id}/tag

Asocia una o más etiquetas a un hilo. Las etiquetas deben existir previamente en su espacio de trabajo; este endpoint no las crea.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`tag_ids`	string[]	Sí	IDs de las etiquetas que se van a asociar

Ejemplo

cURL

curl -X POST "https://be.graph8.com/api/v1/inbox/thr_abc123/tag?channel=email" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_ids": ["tag_interested", "tag_q2"]}'

Generar borrador con IA

GET /inbox/{reply_id}/draft

Genera una respuesta en borrador con IA para el hilo. Esta operación consume créditos. Se devuelve 402 Payment Required cuando la organización no tiene créditos suficientes.

Parámetros de consulta

Parámetro	Tipo	Predeterminado	Descripción
`channel`	string	`email`	Canal del hilo de origen

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/inbox/thr_abc123/draft?channel=email" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": {
    "content": "<p>Tuesday at 10am works great...</p>",
    "plain_content": "Tuesday at 10am works great...",
    "credits_charged": 1
  }
}

Errores

Estado	Significado
`402`	Créditos insuficientes para generar el borrador

Enviar respuesta

POST /inbox/{reply_id}/send

Envía una respuesta por el canal elegido. Los campos requeridos varían según el canal.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
`body`	string	Sí	Cuerpo del mensaje (HTML para email; texto plano para SMS o LinkedIn)
`channel`	string	Sí	`email`, `sms` o `linkedin`
`subject`	string	Solo email	Asunto del email
`to`	string	Email/SMS	Dirección del destinatario o número de teléfono
`from_address`	string	Sí	Buzón de email, número de Twilio o ID de cuenta de LinkedIn

En el caso de LinkedIn, from_address debe ser un ID numérico de cuenta de LinkedIn.

Ejemplos

curl -X POST "https://be.graph8.com/api/v1/inbox/thr_abc123/send" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "body": "<p>Tuesday at 10am works.</p>",
    "subject": "Re: Q2 outbound",
    "to": "[email protected]",
    "from_address": "[email protected]"
  }'

curl -X POST "https://be.graph8.com/api/v1/inbox/thr_sms_xyz/send" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "body": "Confirmed for Tuesday 10am.",
    "to": "+15555550100",
    "from_address": "+15555550199"
  }'

curl -X POST "https://be.graph8.com/api/v1/inbox/conv_li_999/send" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "linkedin",
    "body": "Thanks for connecting!",
    "from_address": "12345"
  }'

Respuesta

{
  "data": {
    "message_id": "msg_outbound_001",
    "status": "sent",
    "channel": "email"
  }
}

Errores

Estado	Significado
`400`	Falta `to` o `from_address` para el canal; `from_address` de LinkedIn no es numérico; canal no compatible