Enviar Email

POST /send-email

Endpoint principal para enviar correos electronicos. Soporta envio inmediato, programado, con plantillas Handlebars, adjuntos y multiples destinatarios.

Autenticacion

Este endpoint no requiere autenticacion mediante API key. Se recomienda incluir el header x-project-id para asociar el envio a un proyecto especifico y habilitar tracking de actividad.

Nota: Este endpoint es de uso interno. Para enviar correos desde tu aplicacion, utiliza los endpoints de la API Publica v1 que requieren autenticacion con Bearer token.

Headers

Header	Tipo	Requerido	Descripcion
`x-project-id`	string	No	ID del proyecto. Asocia el envio a un proyecto.
`x-source`	string	No	Identificador del origen de la solicitud.
`Content-Type`	string	Si	Debe ser `application/json`.

Request Body

Campo	Tipo	Requerido	Descripcion
`html`	string	Si*	Contenido HTML del correo. Requerido si no se usa `templateId`.
`subject`	string	Si	Asunto del correo.
`recipient`	string \| string[]	Si	Direccion de correo del destinatario, o un array de direcciones.
`sender`	string	Si	Direccion de correo del remitente.
`senderName`	string	No	Nombre visible del remitente.
`templateId`	string	No	ID de una plantilla almacenada. Si se proporciona, se usa en lugar de `html`.
`data`	object	No	Objeto con variables para sustitucion Handlebars en la plantilla o HTML.
`email_type`	string	No	Tipo de correo (ej. `transactional`, `marketing`, `automation`).
`campaign_id`	string	No	UUID de la campana asociada.
`automation_run_id`	string	No	UUID de la ejecucion de automatizacion asociada.
`scheduled_at`	string	No	Fecha/hora de envio programado. Ver seccion de programacion.
`timezone`	string	No	Zona horaria para interpretar `scheduled_at`. Ver seccion de programacion.
`cc`	string \| string[]	No	Direccion(es) de correo en copia.
`bcc`	string \| string[]	No	Direccion(es) de correo en copia oculta.
`attachments`	array	No	Lista de objetos de adjuntos. Maximo 10 adjuntos.

Reply-To Automatico (Inbound Email)

Cuando se envia un correo con x-project-id, el sistema genera automaticamente un header Reply-To con el nombre del remitente y una direccion de enrutamiento interna:

Reply-To: "Mi Tienda" <r-x7K9mP2q@rqe.inbound.reallyquickemails.com>

Los clientes de correo (Gmail, Outlook, Apple Mail) muestran el nombre del remitente en lugar de la direccion tecnica. Cuando el destinatario responde, la respuesta se enruta automaticamente a los servidores de ReallyQuickEmails y se asocia al hilo de conversacion original.

Este comportamiento es automatico y no requiere configuracion adicional. Para mas detalles sobre el procesamiento de correos entrantes, consulta POST /api/inbound/ses.

Adjuntos

Cada objeto en el array attachments tiene la siguiente estructura:

Campo	Tipo	Requerido	Descripcion
`filename`	string	Si	Nombre del archivo (ej. `factura.pdf`).
`url`	string	No*	URL publica del archivo. Requerido si no se proporciona `content`.
`content`	string	No*	Contenido del archivo codificado en Base64. Requerido si no se proporciona `url`.
`contentType`	string	No	Tipo MIME del archivo (ej. `application/pdf`). Se infiere del nombre si no se proporciona.

Limites:

Maximo 10 adjuntos por correo.
Maximo 10 MB por adjunto individual.

Programacion de Envio

El campo scheduled_at soporta multiples formatos:

Timestamp ISO 8601

"scheduled_at": "2025-03-15T14:30:00Z"

Lenguaje natural (ingles)

"scheduled_at": "tomorrow at 3pm"
"scheduled_at": "in 2 hours"
"scheduled_at": "next monday at 9am"

Zona horaria (`timezone`)

El campo timezone se usa para interpretar correctamente scheduled_at. Soporta:

Nombre IANA: "America/Santiago", "US/Eastern", "Europe/Madrid"
Offset UTC: "UTC-3", "UTC+5:30"
Numerico: -3, 5.5

Si no se proporciona timezone, se usa la zona horaria por defecto del proyecto (default_timezone). Si el proyecto no tiene zona horaria configurada, se asume UTC.

Ejemplo de Solicitud

Envio inmediato

curl -X POST https://api.reallyquickemails.com/send-email \
  -H "Content-Type: application/json" \
  -H "x-project-id: proj_abc123" \
  -d '{
    "html": "<h1>Hola {{nombre}}</h1><p>Tu pedido #{{pedido}} esta en camino.</p>",
    "subject": "Tu pedido esta en camino",
    "recipient": "cliente@ejemplo.com",
    "sender": "ventas@mitienda.com",
    "senderName": "Mi Tienda",
    "data": {
      "nombre": "Juan",
      "pedido": "12345"
    },
    "email_type": "transactional"
  }'

Envio programado con adjuntos

curl -X POST https://api.reallyquickemails.com/send-email \
  -H "Content-Type: application/json" \
  -H "x-project-id: proj_abc123" \
  -d '{
    "subject": "Reporte mensual - Marzo 2025",
    "recipient": ["gerente@empresa.com", "director@empresa.com"],
    "sender": "reportes@empresa.com",
    "senderName": "Sistema de Reportes",
    "templateId": "reporte-mensual",
    "data": {
      "mes": "Marzo",
      "anio": "2025"
    },
    "scheduled_at": "next monday at 9am",
    "timezone": "America/Santiago",
    "attachments": [
      {
        "filename": "reporte-marzo-2025.pdf",
        "url": "https://storage.ejemplo.com/reportes/marzo-2025.pdf",
        "contentType": "application/pdf"
      }
    ]
  }'

Respuestas

Envio inmediato exitoso

{
  "success": true,
  "messageId": "0102018e-abcd-1234-5678-9abcdef01234",
  "activityId": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "message": "Email sent successfully"
}

Si el correo incluye adjuntos, se agrega el campo attachments_sent:

{
  "success": true,
  "messageId": "0102018e-abcd-1234-5678-9abcdef01234",
  "activityId": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "message": "Email sent successfully",
  "attachments_sent": 2
}

Campo	Tipo	Descripcion
`messageId`	string	ID del mensaje asignado por AWS SES.
`activityId`	string \| null	UUID del registro de actividad en la base de datos. `null` si no se proporciono `x-project-id`.
`attachments_sent`	number	Cantidad de adjuntos enviados. Solo presente si se enviaron adjuntos.

Envio programado exitoso

{
  "success": true,
  "scheduled": true,
  "scheduled_send_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheduled_for": "2025-03-17T12:00:00.000Z",
  "scheduled_for_local": "2025-03-17 09:00 (America/Santiago)",
  "timezone": "America/Santiago",
  "message": "Correo programado para 2025-03-17 09:00 (America/Santiago)"
}

Campo	Tipo	Descripcion
`scheduled_send_id`	string	UUID del correo programado en la base de datos.
`scheduled_for`	string	Fecha y hora de envio en UTC (ISO 8601).
`scheduled_for_local`	string	Fecha y hora de envio en la zona horaria especificada (formato legible).
`timezone`	string	Zona horaria utilizada para la programacion.

Verificacion de Remitente

Cuando se incluye el header x-project-id, el endpoint valida que el remitente (sender) este verificado antes de encolar el envio. Se verifica en este orden:

Email verificado — El email existe en sender_profiles con email_verified = true (verificacion via magic link).
Dominio autenticado — El dominio del email esta registrado en identities con verification_status = verified (verificacion DNS completa).

Si ninguna de las dos condiciones se cumple, se retorna un error 403:

{
  "error": "Sender \"ventas@mitienda.com\" is not verified. Verify the email via magic link or authenticate the domain \"mitienda.com\" first.",
  "code": "SENDER_NOT_VERIFIED"
}

Nota: Para verificar un email como remitente, usa POST /domains/verify-email. Para verificar un dominio completo (recomendado para mejor deliverability), usa POST /domains/register.

Codigos de Error

Codigo	Descripcion
`400`	Solicitud invalida. Faltan campos requeridos, formato incorrecto, o fecha programada en el pasado.
`403`	Remitente no verificado. El email o dominio del sender no esta verificado. Ver seccion de verificacion.
`404`	Plantilla no encontrada (cuando se usa `templateId`).
`413`	Adjunto excede el limite de tamano (10 MB).
`415`	Tipo de contenido no soportado. Se requiere `application/json`.
`500`	Error interno del servidor.
`502`	Error de comunicacion con el servicio de envio de correo (AWS SES).
`504`	Timeout en la comunicacion con el servicio de envio de correo.

Ejemplo de error

{
  "success": false,
  "error": "Missing required field: subject"
}

Enviar Email

On this page