# Enviar un correo desde Gmail
> Envía un correo desde la cuenta de Gmail de la conexión, a lo más una vez.
{/* AUTO-GENERATED by @emisso/codegen. DO NOT EDIT. */}
| | |
| ------------------- | ----------------------------------------------------------------- |
| **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`](/docs/referencia/conexiones/estado-consultar).
## Qué hace [#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 [#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
```json
{
"$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 [#ejemplo]
```bash title="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"}}'
```
```json title="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):**
```json
{
"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 [#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í | Identificador del correo enviado; null si el envío es desconocido o Gmail no lo informó. |
| `hiloId` | string `^[0-9a-fA-F]{8,32}$` | null | sí | Identificador del hilo del correo enviado; null si no se conoce. |
| `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
```json
{
"$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 [#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](/docs/referencia/errores).