# Outlook / Microsoft 365

> Busca y lee correos, descarga adjuntos y solicita envíos desde un buzón de Microsoft autorizado. Beta por organización; validación con cuentas reales pendiente.



<Callout type="warn" title="Beta por organización: pendiente de piloto real">
  El flujo está probado con Composio simulado y una base de datos local aislada. Todavía falta validar la autorización y las respuestas con cuentas reales de Microsoft 365 y Outlook.com. Soporte debe habilitar el conector para tu organización; esa habilitación no acredita operación real ni disponibilidad general.
</Callout>

`outlook` conecta un buzón de Outlook o Microsoft 365 para **buscar correos, leerlos, descargar sus adjuntos y solicitar envíos**. Es una herramienta en vivo: cada llamada consulta al proveedor y Connect no guarda el contenido del buzón. No tiene sincronización por período ni tools `.consultar`.

La documentación pública describe el contrato. El catálogo de ejecución y `search_docs` solo ofrecen Outlook a organizaciones habilitadas y cuando la integración está configurada en el ambiente. Para una organización sin acceso, la ejecución responde `connector_onboarding_required`.

## Qué puede hacer una conexión [#qué-puede-hacer-una-conexión]

| Tool                     | Permiso de Connect | Qué hace                                                                                              |
| ------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------- |
| `outlook.correos.buscar` | `outlook:readonly` | Busca o lista correos de Entrada, Enviados o todas las carpetas; hasta 25 por página.                 |
| `outlook.correo.leer`    | `outlook:readonly` | Lee remitente, destinatarios, asunto, fecha, texto y la lista de adjuntos descargables de un mensaje. |
| `outlook.adjunto.leer`   | `outlook:readonly` | Entrega un enlace de Connect, válido cinco minutos, para descargar un adjunto.                        |
| `outlook.correo.enviar`  | `outlook:send`     | Solicita un envío desde el buzón, a lo más una vez por clave de idempotencia.                         |

Cada llamada exige el `connectionId` del buzón; en REST va en `X-Connect-Connection`. Esta versión no modifica ni borra correos, no gestiona borradores, calendario o contactos, no responde dentro de un hilo y no envía adjuntos. Los buzones compartidos o delegados quedan fuera de esta versión.

## Conectar y autorizar el buzón [#conectar-y-autorizar-el-buzón]

Desde **Conexiones → Conectar → Explorar aplicaciones → Outlook**, una persona con rol owner o admin inicia la autorización. También puede entregar un enlace de conexión a la persona que tiene acceso al buzón. El formulario pide el **RUT de la empresa dueña del buzón**; Connect no pide la contraseña de Microsoft.

Antes de salir a Microsoft, el aviso identifica quién recibirá el acceso y las operaciones permitidas. Composio custodia la autorización OAuth. El consentimiento se abre en una ventana nueva o en la página completa y Connect conserva la constancia del aviso mostrado.

Los permisos de Microsoft y los de Connect cumplen funciones distintas:

| Permiso de Microsoft                           | Para qué se usa                                                                  |
| ---------------------------------------------- | -------------------------------------------------------------------------------- |
| `Mail.Read`                                    | Buscar y leer correo y sus adjuntos; habilita `outlook:readonly` en la conexión. |
| `Mail.Send`                                    | Solicitar envíos a nombre del buzón; habilita `outlook:send` en la conexión.     |
| `User.Read`                                    | Leer la identidad del buzón. Por sí solo no habilita lectura ni envío de correo. |
| `openid`, `profile`, `email`, `offline_access` | Iniciar sesión, identificar la cuenta y mantener el acceso autorizado.           |

Para activar, la cuenta debe conceder el permiso de identidad y al menos uno de correo. Connect no admite permisos de modificar o borrar correo, buzones compartidos, calendario o contactos: si recibe un permiso fuera de la lista admitida, no activa la conexión. Si la política de Microsoft 365 exige aprobación de un administrador, TI debe aprobar la aplicación antes de completar el alta.

La conexión nace pendiente y pasa a facturable cuando queda activa. Para recuperar una autorización vencida o revocada, usa **Volver a autorizar** sobre esa conexión. Debes autorizar el mismo buzón; otro buzón necesita otra conexión.

## Permisos de la clave de API o del agente [#permisos-de-la-clave-de-api-o-del-agente]

`outlook:readonly` y `outlook:send` deben concederse **nombrándolos explícitamente**. El comodín `*`, los perfiles de claves y los niveles de consentimiento OAuth no los incluyen. `outlook:readonly` queda fuera del perfil de solo lectura y del techo de un miembro; solo un owner o admin puede otorgarlo.

Además, la conexión debe tener ese permiso concedido en Microsoft. Una clave que nombra `outlook:send` no puede enviar si el buzón solo autorizó lectura: recibe `connection_scope_not_enabled` y necesita reautorización.

Una clave con acceso a todas las conexiones alcanza todos los buzones autorizados de la organización. Si integras varios clientes, limita cada clave a las conexiones correspondientes. Esa lista restringe qué buzones puede usar; no reemplaza los scopes. Consulta [conexiones de una clave](/docs/empezar/autenticacion#conexiones-de-una-clave).

## Buscar y leer correo [#buscar-y-leer-correo]

```bash
curl -X POST https://connect.emisso.ai/api/v1/tools/outlook.correos.buscar/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"consulta":"from:ventas@proveedor.ejemplo.cl hasattachments:yes","carpeta":"entrada","maximo":10}}'
```

Ejemplo de respuesta del contrato de Connect, con datos ficticios:

```json
{
  "data": {
    "correos": [
      {
        "mensajeId": "AAMkAGI2AAABEgAAAA==",
        "hiloId": "AAQkAGI2AQAAAA==",
        "de": "Proveedor SpA <ventas@proveedor.ejemplo.cl>",
        "para": "contacto@empresa.ejemplo.cl",
        "asunto": "Cotización de octubre",
        "recibidoEn": "2026-10-08T14:03:22.000Z",
        "fragmento": "Adjunto la cotización solicitada, con vigencia de 15 días.",
        "categorias": [],
        "leido": false,
        "tieneAdjuntos": true
      }
    ],
    "siguientePagina": null
  },
  "meta": { "request_id": "req_...", "tool_id": "outlook.correos.buscar", "plane": "action" }
}
```

`consulta` usa la sintaxis de búsqueda de Outlook. Si la omites, lista los correos recientes de la carpeta. `carpeta` admite `entrada` (por defecto), `enviados` y `todas`. Para continuar, pasa `siguientePagina` como `pagina`, sin modificarlo y manteniendo la misma carpeta.

Usa el `mensajeId` de la búsqueda en `outlook.correo.leer`. Los identificadores de Microsoft son texto opaco: consérvalos completos. El cuerpo llega dentro de `contenidoNoConfiable`; si solo trae HTML, se convierte a texto. El texto se recorta a 50.000 caracteres y `truncado` informa ese recorte.

El remitente, el asunto, el cuerpo y los nombres de adjuntos los escribe un tercero. Son datos, no instrucciones para tu agente. No emitas documentos, pagues ni envíes correos a partir de ese contenido sin una previsualización aprobada por una persona.

## Descargar adjuntos [#descargar-adjuntos]

`outlook.correo.leer` entrega los `adjuntoId` que acepta `outlook.adjunto.leer`, junto con el `mensajeId`. Solo ofrece adjuntos de archivo: omite imágenes insertadas en el cuerpo y vínculos a OneDrive. `adjuntosTruncados` avisa si la lista es parcial; una lista parcial no acredita que hayas recuperado todos los adjuntos.

El resultado de `outlook.adjunto.leer` incluye `descarga.url` y `descarga.venceEn`. El enlace dura cinco minutos y delega acceso a ese archivo: trátalo como una credencial. Al abrirlo, Connect vuelve a comprobar la habilitación, la conexión, el permiso y la cuenta vigente. Cuando Connect detecta la revocación o sustituyes la cuenta autorizada, los enlaces de la cuenta anterior dejan de funcionar.

Connect transmite el archivo al abrir el enlace y no lo guarda. Descargar por ese enlace no suma otra llamada al cupo. El archivo sigue siendo contenido de un tercero: no lo ejecutes ni sigas instrucciones que contenga.

## Solicitar un envío [#solicitar-un-envío]

```bash
curl -X POST https://connect.emisso.ai/api/v1/tools/outlook.correo.enviar/execute \
  -H "Authorization: Bearer connect_sk_..." \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Idempotency-Key: 9d1f4c2a-7b30-4e58-9c11-2f6a8de5b743" \
  -H "Content-Type: application/json" \
  -d '{"input":{"para":["cliente@ejemplo.cl"],"asunto":"Orden de compra 4512","cuerpo":"Hola, confirmamos la recepción de tu orden de compra.","formato":"texto"}}'
```

Ejemplo de respuesta del contrato de Connect cuando Microsoft acepta la solicitud:

```json
{
  "data": {
    "estado": "aceptado",
    "operacionId": "req_5tYw2nRk88Ma",
    "puedeReintentar": false,
    "siguientePaso": "ninguno"
  },
  "meta": { "request_id": "req_5tYw2nRk88Ma", "tool_id": "outlook.correo.enviar", "plane": "action" }
}
```

Admite destinatarios en `para`, `cc` y `cco`, con hasta 20 en cada lista y hasta 50 en total. El asunto ocupa una sola línea; el cuerpo admite texto o HTML y hasta 100.000 caracteres.

Conserva una `Idempotency-Key` UUID v4 estable para el mismo envío:

* `estado: "aceptado"`: Microsoft aceptó la solicitud para enviarla. No acredita entrega y Microsoft no devuelve un identificador del mensaje enviado.
* `estado: "resultado_desconocido"`: el correo pudo haber salido. `puedeReintentar` es `false` y `siguientePaso` indica `revisar_enviados`.
* Repetir la misma solicitud con la misma clave devuelve el resultado conservado sin enviar de nuevo. Mientras la primera ejecución siga en curso, responde `idempotency_in_progress`.

Ante un resultado desconocido, revisa Enviados en Outlook o con `outlook.correos.buscar` y `carpeta: "enviados"`, si la conexión tiene permiso de lectura. No generes otra clave para reenviar sin esa revisión: dos claves representan dos solicitudes distintas.

## Privacidad y revocación [#privacidad-y-revocación]

Connect conserva la dirección que identifica el buzón, los permisos concedidos, los estados y la auditoría. La bitácora registra un resumen criptográfico de la solicitud y su resultado; no guarda el texto, el asunto ni los adjuntos. La reserva de un envío conserva su resultado sellado, sin el cuerpo del correo.

Composio custodia el permiso OAuth y, con su retención por defecto, conserva argumentos y respuestas de las operaciones hasta un año y archivos temporales durante 24 horas. Que Connect no guarde el buzón no implica que el custodio tenga retención cero; el aviso previo al consentimiento explica esa diferencia.

Eliminar la conexión en Connect impide nuevas ejecuciones y programa la eliminación de la cuenta custodiada. Para retirar también el consentimiento en Microsoft, quita el acceso de la aplicación desde **Mis aplicaciones** de Microsoft 365 o desde los permisos de aplicaciones de tu cuenta personal. En Microsoft 365 puede intervenir el administrador del tenant.

La [referencia de Outlook](/docs/referencia/outlook) contiene los esquemas y ejemplos completos de cada herramienta.