Enviar un correo desde Gmail


Tool ID	`gmail.correo.enviar`
Nombre MCP	`gmail__correo__enviar`
Conector	`gmail`
Plano	`action`
Scope (permiso)	`gmail:send`
Auth	`connection_credentials`
Versión	`1`
Sensible	sí
Deprecado	no
Comportamiento	readOnly=false, destructive=true, 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_write 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

Exige un UUID v4 como clave de idempotencia; consérvala. Si estado es resultado_desconocido, el correo pudo haber salido: no reintentes ni generes otra clave; revisa Enviados (con gmail.correos.buscar e in:sent si la conexión puede leer) o pídeselo a la persona. Requiere que la cuenta haya autorizado el envío en Google.

Entrada

Campo	Tipo	Requerido	Descripción
`para`	lista de string `^(?!\.)(?!.\.\.)([A-Za-z0-9_'+\-\.])[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`	sí	Destinatarios directos. Al menos uno.
`cc`	lista de string `^(?!\.)(?!.\.\.)([A-Za-z0-9_'+\-\.])[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`	no	Destinatarios en copia.
`cco`	lista de string `^(?!\.)(?!.\.\.)([A-Za-z0-9_'+\-\.])[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`	no	Destinatarios en copia oculta.
`asunto`	string	sí	Asunto del correo, en una sola línea.
`cuerpo`	string	sí	Cuerpo del correo, en texto o en HTML según `formato`.
`formato`	`"texto"` · `"html"`	no · default `"texto"`	`texto` (por defecto) o `html`.

JSON Schema de entrada

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "para": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 320,
        "format": "email",
        "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      },
      "description": "Destinatarios directos. Al menos uno."
    },
    "cc": {
      "description": "Destinatarios en copia.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 320,
        "format": "email",
        "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      }
    },
    "cco": {
      "description": "Destinatarios en copia oculta.",
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 320,
        "format": "email",
        "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
      }
    },
    "asunto": {
      "type": "string",
      "minLength": 1,
      "maxLength": 998,
      "description": "Asunto del correo, en una sola línea."
    },
    "cuerpo": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100000,
      "description": "Cuerpo del correo, en texto o en HTML según `formato`."
    },
    "formato": {
      "default": "texto",
      "description": "`texto` (por defecto) o `html`.",
      "type": "string",
      "enum": [
        "texto",
        "html"
      ]
    }
  },
  "required": [
    "para",
    "asunto",
    "cuerpo"
  ],
  "additionalProperties": false
}

Ejemplo

curl

curl -X POST https://connect.emisso.ai/api/v1/tools/gmail.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 4512. Saludos.","formato":"texto"}}'

MCP · meta-tool execute_write

{
  "tool": "gmail.correo.enviar",
  "params": {
    "para": [
      "cliente@ejemplo.cl"
    ],
    "asunto": "Orden de compra 4512",
    "cuerpo": "Hola, confirmamos la recepción de tu orden de compra 4512. Saludos.",
    "formato": "texto"
  },
  "connectionId": "conn_9tKfR2mQx4Vb",
  "idempotencyKey": "9d1f4c2a-7b30-4e58-9c11-2f6a8de5b743"
}

Clave de idempotencia obligatoria. Sin ella la llamada responde idempotency_key_missing. Genera un UUID v4 nuevo por operación y envíalo en Idempotency-Key (REST) o en idempotencyKey (MCP). Repite la misma clave solo al reintentar esa operación.

Salida esperada (200):

{
  "data": {
    "estado": "enviado",
    "mensajeId": "18c3a2b4d5e6f710",
    "hiloId": "18c3a2b4d5e6f710",
    "operacionId": "req_5tYw2nRk88Ma",
    "puedeReintentar": false,
    "siguientePaso": "ninguno"
  },
  "meta": {
    "request_id": "req_…",
    "tool_id": "gmail.correo.enviar",
    "plane": "action",
    "latency_ms": 7410,
    "audit_status": "recorded"
  }
}

Conserva la Idempotency-Key hasta confirmar el resultado. Si estado fuera resultado_desconocido, repite la llamada con la misma clave, nunca con otra.

Salida

Campo	Tipo	Requerido	Descripción
`estado`	`"enviado"` · `"resultado_desconocido"`	sí	`enviado` si Gmail confirmó el envío; `resultado_desconocido` si el correo pudo haber salido.
`mensajeId`	string `^[0-9a-fA-F]{8,32}$`	null	sí
`hiloId`	string `^[0-9a-fA-F]{8,32}$`	null	sí
`operacionId`	string	sí	request_id de la operación: el de la primera solicitud con esta clave.
`puedeReintentar`	booleano	sí	Siempre false: reintentar con otra clave duplicaría el correo.
`siguientePaso`	`"ninguno"` · `"revisar_enviados"`	sí	`revisar_enviados` cuando el resultado es desconocido: revisa la carpeta Enviados antes de hacer nada más.

JSON Schema de salida

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "estado": {
      "type": "string",
      "enum": [
        "enviado",
        "resultado_desconocido"
      ],
      "description": "`enviado` si Gmail confirmó el envío; `resultado_desconocido` si el correo pudo haber salido."
    },
    "mensajeId": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8,32}$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Identificador del correo enviado; null si el envío es desconocido o Gmail no lo informó."
    },
    "hiloId": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{8,32}$"
        },
        {
          "type": "null"
        }
      ],
      "description": "Identificador del hilo del correo enviado; null si no se conoce."
    },
    "operacionId": {
      "type": "string",
      "description": "request_id de la operación: el de la primera solicitud con esta clave."
    },
    "puedeReintentar": {
      "type": "boolean",
      "const": false,
      "description": "Siempre false: reintentar con otra clave duplicaría el correo."
    },
    "siguientePaso": {
      "type": "string",
      "enum": [
        "ninguno",
        "revisar_enviados"
      ],
      "description": "`revisar_enviados` cuando el resultado es desconocido: revisa la carpeta Enviados antes de hacer nada más."
    }
  },
  "required": [
    "estado",
    "mensajeId",
    "hiloId",
    "operacionId",
    "puedeReintentar",
    "siguientePaso"
  ],
  "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.
`idempotency_key_missing`	400	no	Genera un UUID v4, envíalo como Idempotency-Key y reutilízalo solo para reintentos de esta misma operación.
`idempotency_in_progress`	409	sí	Espera unos segundos y reintenta con la MISMA clave. Generar una nueva para la misma operación es lo que duplica el efecto.
`idempotency_conflict`	409	no	Genera una clave nueva para una operación nueva; reutiliza la clave solo para reintentar la misma.

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.