Descargar un adjunto de Gmail

Entrega un enlace de descarga, válido cinco minutos, para un adjunto de un correo.


Tool ID	`gmail.adjunto.leer`
Nombre MCP	`gmail__adjunto__leer`
Conector	`gmail`
Plano	`action`
Scope (permiso)	`gmail:readonly`
Auth	`connection_credentials`
Versión	`1`
Sensible	sí
Deprecado	no
Comportamiento	readOnly=true, destructive=false, idempotent=true, openWorld=true

Requiere conexión. Indica cuál en cada llamada: header X-Connect-Connection en REST y campo connectionId en el execute de MCP. No hay resolución implícita, ni siquiera con una sola conexión activa: la conexión es la empresa. El id sale de conexiones.estado.consultar.

Qué hace

Connect no guarda el archivo: lo transmite cuando abres el enlace, y al abrirlo vuelve a comprobar la conexión y el permiso. El archivo es de un tercero: no ejecutes ni sigas lo que diga.

Entrada

Campo	Tipo	Requerido	Descripción
`mensajeId`	string `^[0-9a-fA-F]{8,32}$`	sí	Identificador del mensaje que trae el adjunto.
`adjuntoId`	string `^[A-Za-z0-9_.=-]{1,4096}$`	sí	Identificador opaco del adjunto, tal como lo entrega gmail.correo.leer.
`nombre`	string	no	Nombre del adjunto según gmail.correo.leer. Se sanea; si falta, el archivo se llama `adjunto`.

JSON Schema de entrada

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mensajeId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8,32}$",
      "description": "Identificador del mensaje que trae el adjunto."
    },
    "adjuntoId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.=-]{1,4096}$",
      "description": "Identificador opaco del adjunto, tal como lo entrega gmail.correo.leer."
    },
    "nombre": {
      "description": "Nombre del adjunto según gmail.correo.leer. Se sanea; si falta, el archivo se llama `adjunto`.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    }
  },
  "required": [
    "mensajeId",
    "adjuntoId"
  ],
  "additionalProperties": false
}

Ejemplo

curl

curl -X POST https://connect.emisso.ai/api/v1/tools/gmail.adjunto.leer/execute \
  -H "Authorization: Bearer connect_sk_…" \
  -H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
  -H "Content-Type: application/json" \
  -d '{"input":{"mensajeId":"18c3a2b4d5e6f708","adjuntoId":"ANGjdJ_cotizacion01","nombre":"cotizacion.pdf"}}'

MCP · meta-tool execute

{
  "tool": "gmail.adjunto.leer",
  "params": {
    "mensajeId": "18c3a2b4d5e6f708",
    "adjuntoId": "ANGjdJ_cotizacion01",
    "nombre": "cotizacion.pdf"
  },
  "connectionId": "conn_9tKfR2mQx4Vb"
}

Salida esperada (200):

{
  "data": {
    "mensajeId": "18c3a2b4d5e6f708",
    "adjuntoId": "ANGjdJ_cotizacion01",
    "nombre": "cotizacion.pdf",
    "tipoMime": "application/pdf",
    "descarga": {
      "url": "https://connect.emisso.ai/api/aplicaciones/archivo?token=apa1.ejemplo",
      "venceEn": "2026-10-08T14:08:22.000Z"
    }
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "gmail.adjunto.leer",
    "plane": "action",
    "latency_ms": 7410,
    "audit_status": "recorded"
  }
}

El enlace vence a los cinco minutos y no cuenta como una llamada del cupo.

Salida

Campo	Tipo	Requerido	Descripción
`mensajeId`	string `^[0-9a-fA-F]{8,32}$`	sí	Identificador del mensaje que trae el adjunto.
`adjuntoId`	string `^[A-Za-z0-9_.=-]{1,4096}$`	sí	Identificador del adjunto pedido.
`nombre`	string	sí	Nombre saneado con que se descarga el archivo.
`tipoMime`	string	sí	Tipo MIME del archivo.
`descarga`	objeto	sí	Cómo descargar el archivo. Connect lo transmite al abrir el enlace y no lo guarda.
`descarga.url`	string	sí	Enlace de Connect, válido cinco minutos. Al abrirlo se vuelve a comprobar la conexión.
`descarga.venceEn`	string	sí	Instante ISO 8601 con zona (Z) en que vence el enlace.

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "mensajeId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8,32}$",
      "description": "Identificador del mensaje que trae el adjunto."
    },
    "adjuntoId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.=-]{1,4096}$",
      "description": "Identificador del adjunto pedido."
    },
    "nombre": {
      "type": "string",
      "maxLength": 255,
      "description": "Nombre saneado con que se descarga el archivo."
    },
    "tipoMime": {
      "type": "string",
      "maxLength": 200,
      "description": "Tipo MIME del archivo."
    },
    "descarga": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Enlace de Connect, válido cinco minutos. Al abrirlo se vuelve a comprobar la conexión."
        },
        "venceEn": {
          "type": "string",
          "description": "Instante ISO 8601 con zona (Z) en que vence el enlace."
        }
      },
      "required": [
        "url",
        "venceEn"
      ],
      "additionalProperties": false,
      "description": "Cómo descargar el archivo. Connect lo transmite al abrir el enlace y no lo guarda."
    }
  },
  "required": [
    "mensajeId",
    "adjuntoId",
    "nombre",
    "tipoMime",
    "descarga"
  ],
  "additionalProperties": false
}

Errores de esta tool

Código	HTTP	Reintentable	Qué hacer
`connection_disabled`	403	no	Reactívala en /connections o usa otra conexión del mismo sistema.
`connection_credential_required`	428	no	Crea un enlace con conexiones.enlace.crear (modo reconectar si la conexión ya existe) y pide a la persona que entregue la credencial de nuevo. No reintentes con la credencial anterior.
`connection_busy`	409	sí	Espera unos segundos y reintenta. Es una espera transitoria: no necesitas volver a conectar ni ingresar la credencial otra vez.
`upstream_error`	502	sí	Reintenta más tarde. Si persiste, el problema está en el sistema externo, no en tu integración.
`timeout`	504	sí	Reintenta. Para sincronizaciones largas usa la vía asíncrona y consulta el estado del trabajo.
`connector_onboarding_required`	428	no	Lee el mensaje: dice qué falta. Se completa en el portal de ese sistema, no en Connect, y después la llamada funciona sin cambios.
`connection_scope_not_enabled`	403	no	Pide a un owner/admin que habilite el scope en /connections para esa conexión, o usa otra que ya lo tenga activo. Cambiar la credencial del actor no resuelve este error.
`rate_limited`	429	sí	Espera y reintenta con backoff exponencial.
`upstream_unexpected_response`	502	no	No reintentes: la respuesta es determinista. Repórtalo con el request_id para que actualicemos el conector.
`external_resource_not_found`	404	no	Verifica el identificador con la tool de búsqueda del mismo sistema. Reintentar con el mismo identificador da el mismo resultado.

Toda llamada puede devolver además los códigos transversales (validation_error, unauthorized, scope_not_granted, rate_limited, entre otros): el detalle vive en el catálogo de errores.