# Bandeja de entrada

> Bandeja de entrada multicanal: liste conversaciones, genere borradores con IA y envíe respuestas por correo electrónico, SMS o LinkedIn

Source: https://docs.graph8.com/es/developers/inbox/

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](https://be.graph8.com/api/v1/docs).

> **Caution: Use un id de hilo real**
> Cada `{reply_id}` de esta página es el `id` de un hilo devuelto por [`GET /inbox`](#listar-hilos-de-la-bandeja-de-entrada). Los ids de hilo son cadenas opacas (un id de hilo de Gmail, un Message-ID de correo, etc.), así que no hay un formato para construirlos: léalos siempre de la lista. Los ejemplos lo guardan primero en `$THREAD_ID`. Los ids de las respuestas de ejemplo son solo ilustrativos; enviar uno devuelve `422`.
>
> ```bash
> THREAD_ID=$(curl -s "https://be.graph8.com/api/v1/inbox?channel=email&page_size=1" \
>   -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].id')
> ```

---

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

### Ejemplo

**cURL**

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

**Python**

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

### Respuesta

```json
{
  "data": [
    {
      "id": "<id del hilo: úselo como {reply_id}>",
      "channel": "email",
      "subject": "Re: Q2 outbound",
      "contact": {"email": "jane@acme.com", "name": "Jane Smith"},
      "messages": [
        {
          "message_id": "msg_001",
          "from_address": "jane@acme.com",
          "to_addresses": ["rep@graph8.com"],
          "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": "rep@graph8.com", "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**

```bash
curl "https://be.graph8.com/api/v1/inbox/$THREAD_ID?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) |
| `422` | `reply_id` es un id de ejemplo de esta página, no un hilo real |

---

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

```bash
curl -X POST "https://be.graph8.com/api/v1/inbox/$THREAD_ID/assign?channel=email" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignee_email": "rep@graph8.com"}'
```

### Respuesta

```json
{ "data": { "assigned": true, "assignee": "rep@graph8.com", "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**

```bash
curl -X POST "https://be.graph8.com/api/v1/inbox/$THREAD_ID/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**

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

### Respuesta

```json
{
  "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 |
| `404` | No existe un hilo con este `reply_id` en este `channel`; no se cobran créditos |
| `422` | `reply_id` es un id de ejemplo de esta página, no un hilo real |

---

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

`$THREAD_ID`, `$SMS_THREAD_ID` y `$LINKEDIN_THREAD_ID` son ids de hilo leídos de `GET /inbox` con `channel=email`, `sms` y `linkedin` respectivamente.

### Ejemplos

**Email**

```bash
curl -X POST "https://be.graph8.com/api/v1/inbox/$THREAD_ID/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": "jane@acme.com",
    "from_address": "rep@graph8.com"
  }'
```

**SMS**

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

**LinkedIn**

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

### Respuesta

```json
{
  "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 |
| `403` | Su clave no puede enviar como `from_address` |
| `422` | `reply_id` es un id de ejemplo de esta página, no un hilo real; o el proveedor rechazó una dirección de destinatario mal formada |