Skip to main content
POST
/
marketplace
/
messaging
/
send-email
Enviar email
curl --request POST \
  --url http://api.gu1.ai/marketplace/messaging/send-email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "<string>",
  "fromEmail": "<string>",
  "fromSenderId": {},
  "templateParams": {},
  "templateId": {},
  "subject": "<string>",
  "htmlBody": "<string>",
  "textBody": "<string>"
}
'
Envía un email transaccional para la organización autenticada. Requiere la integración Email en Marketplace y proveedor configurado. Requisitos generales en Resumen de mensajería.

​
Endpoint

POST https://api.gu1.ai/marketplace/messaging/send-email

​
Cabeceras

Authorization: Bearer TU_API_KEY
Content-Type: application/json
X-Organization-ID: <uuid>   # opcional si hay varias orgs

​
Cuerpo de la petición

​
Común

​
to
string
required
Email del destinatario.
​
fromEmail
string
Remitente completo. Debe estar dado de alta y el dominio verificado. Excluyente con fromSenderId.
​
fromSenderId
string (UUID)
UUID del remitente en Configuración → Email → Remitentes. Excluyente con fromEmail.
Si no envías fromEmail ni fromSenderId, la API usa el remitente por defecto del proveedor de mensajería (variables de entorno del servidor, p. ej. MS_PROVIDER_FROM_EMAIL / MS_PROVIDER_FROM_NAME, con respaldo tipo SENDGRID_FROM_* o noreply@gueno.com + Güeno). Eso es el comportamiento esperado, no un error.
​
templateParams
object
Valores para {{placeholders}} en asunto, HTML, texto o plantilla. Por defecto {}.

​
Modo A — Plantilla

​
templateId
string (UUID)
required
Plantilla con canal email.
No envíes htmlBody ni textBody.
​
subject
string
Opcional si la plantilla define asunto o queda vacío tras variables.

​
Modo B — Contenido inline

Sin templateId.
​
subject
string
required
Asunto; admite {{variables}} con templateParams.
​
htmlBody
string
HTML (~500k caracteres máx.).
​
textBody
string
Texto plano; si no hay HTML se envuelve en HTML mínimo.
Obligatorio al menos uno de htmlBody o textBody.

​
Ejemplo — plantilla

{
  "to": "usuario@ejemplo.com",
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "templateParams": { "name": "Ada", "token": "482910" },
  "fromEmail": "noreply@tudominio.com"
}

​
Ejemplo — HTML con variables

{
  "to": "usuario@ejemplo.com",
  "subject": "Tu código: {{token}}",
  "htmlBody": "<p>Tu código es <strong>{{token}}</strong></p>",
  "templateParams": { "token": "482910" }
}

​
Errores y códigos HTTP

En la mayoría de los casos la API responde con JSON { "success": false, "error": "<mensaje en inglés>" }. Los cuerpos inválidos pueden devolver otro formato (p. ej. detalle Zod) con 400. Todos los error de negocio van en inglés.
SituaciónHTTPEjemplo de error (texto real de la API)
Integración Email desactivada para la org400Email integration is not active. Enable Email (global_sender_email) in Applications (Marketplace) for this organization.
Servidor sin URL del proveedor de mensajería400MS_PROVIDER_URL is not configured on the server. Configure the messaging provider to send email.
Precio > 0 y sin saldo ni cupo de pack400Insufficient balance for this send (cost … credits). … (ver respuesta completa)
Envío OK pero fallo al registrar cobro400Insufficient balance to record billing for this send. Current balance (…) is below required (…). …
templateId y cuerpo inline a la vez400 (validación)Use either templateId + templateParams, or htmlBody/textBody only — not both.
Sin plantilla ni cuerpo400 (validación)Provide templateId or htmlBody/textBody.
Modo inline sin subject400 (validación)subject is required when not using a template.
Plantilla inexistente u otra organización404Template not found or not accessible for this organization.
Plantilla con otro canal (no email)400Template channel is "<channel>"; email is required.
Plantilla sin asunto tras variables400The template has no subject or it is empty after replacing variables. Send subject in the request body or set the subject on the template.
fromSenderId y fromEmail juntos400Send only one of fromSenderId or fromEmail, not both.
fromSenderId desconocido400fromSenderId does not match a sender for this organization. Check Settings → Email → Senders.
Dominio del fromEmail no registrado400Domain "…" is not registered in Güeno. Add and verify it under Settings → Email → Domains before using sender "…".
Dominio sin verificar400Domain "…" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains.
Dominio OK pero remitente no dado de alta400Sender "…" is not configured. Add it under Settings → Email → Senders (domain "…" is already verified).
Asunto vacío tras {{…}} (inline)400Subject is empty after replacing variables.
Cuerpo vacío tras render400htmlBody or textBody is empty after rendering.
Sin organización en sesión401{ "error": "Organization ID not found" } (sin campo success)
Tras pasar validaciones, el proveedor externo puede devolver { "success": false, "error": "…" } con 200; comprueba siempre success y error.