API Pública v1

La API publica v1 expone endpoints autenticados mediante Secret Key para integraciones externas. Los endpoints bajo /v1/ validan la clave de API y reenvian la solicitud a la funcion Edge de Supabase correspondiente, donde se aplica la logica de negocio (supresion, CAN-SPAM, renderizado de plantillas).

Base URL: https://api.reallyquickemails.com

Autenticacion

Todos los endpoints de la API publica requieren autenticacion mediante Bearer token con una clave de proyecto:

Authorization: Bearer sk_proj_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Las claves de proyecto (sk_proj_...) se generan desde el panel de administracion del proyecto. Si la clave es invalida o no se proporciona, el servidor responde con 401 Unauthorized.

Respuesta de error de autenticacion

{
  "success": false,
  "error": "Unauthorized: Invalid or missing API key"
}

POST /v1/send-email

Envia un correo electronico individual. Este endpoint valida la API Key y reenvia la solicitud al pipeline interno de envio (BullMQ → SES) aplicando la logica correspondiente a este flujo: validacion de remitente verificado, lista de supresion y tracking. Los headers de unsubscribe / footer CAN-SPAM se aplican automaticamente solo en envios de campana; para envios individuales podes pasarlos via custom_headers en el endpoint interno o usar /v1/send-batch.

Headers

Header	Tipo	Requerido	Descripcion
`Authorization`	string	Si	`Bearer sk_proj_...`
`Content-Type`	string	Si	`application/json`

Request Body

Campo	Tipo	Requerido	Descripcion
`recipient_email`	string \| string[]	Si	Direccion(es) del destinatario. Acepta string (1 destinatario) o array (max 50). Para volúmenes mayores usa `/v1/send-batch`.
`sender_email`	string	Si	Direccion del remitente (dominio verificado).
`sender_name`	string	No	Nombre visible del remitente. Si se omite, el inbox muestra solo `sender_email`.
`html_body`	string	Si	Contenido HTML del correo.
`text_body`	string	No	Versión plain text del correo (multipart fallback). Recomendado para mejorar deliverability y accessibility.
`subject`	string	No	Asunto del correo.
`cc`	string \| string[]	No	Direccion(es) en copia. Max 10.
`bcc`	string \| string[]	No	Direccion(es) en copia oculta. Max 10.
`attachments`	array	No	Lista de adjuntos (max 10, max 10MB cada uno). Estructura: `{ filename, url \| content (base64), contentType? }`.

Ejemplo simple

curl -X POST https://api.reallyquickemails.com/v1/send-email \
  -H "Authorization: Bearer sk_proj_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": "usuario@ejemplo.com",
    "sender_email": "hola@miapp.com",
    "sender_name": "Mi Empresa",
    "subject": "Bienvenido a nuestra plataforma",
    "html_body": "<h1>Bienvenido!</h1><p>Gracias por registrarte.</p>"
  }'

Ejemplo con múltiples destinatarios + cc + adjunto

curl -X POST https://api.reallyquickemails.com/v1/send-email \
  -H "Authorization: Bearer sk_proj_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": ["a@empresa.com", "b@empresa.com"],
    "cc": "supervisor@empresa.com",
    "sender_email": "notificaciones@miapp.com",
    "sender_name": "Mi Empresa",
    "subject": "Reporte diario",
    "html_body": "<h1>Reporte</h1><p>Adjunto encontrarás el detalle.</p>",
    "attachments": [
      {
        "filename": "reporte.pdf",
        "url": "https://storage.miapp.com/reportes/2026-04-28.pdf",
        "contentType": "application/pdf"
      }
    ]
  }'

Respuesta exitosa (200)

{
  "message": "Email sent successfully",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "123e4567-e89b-12d3-a456-426614174000"
}

Respuesta cuando el destinatario esta suprimido (200)

{
  "message": "Email skipped — recipient is suppressed",
  "skipped": true,
  "suppression_reason": "bounce",
  "recipient": "usuario@ejemplo.com"
}

Codigos de Error

Codigo	Descripcion
`400`	`Missing required fields: recipient_email, sender_email, html_body`
`401`	API Key invalida o no proporcionada.
`500`	Error interno del servidor.

POST /v1/send-template-email

Envia un correo electronico utilizando una plantilla pre-configurada con sustitucion de variables. Ideal para integraciones donde el contenido HTML se gestiona desde el editor de ReallyQuickEmails y tu sistema solo proporciona los datos dinamicos.

Headers

Header	Tipo	Requerido	Descripcion
`Authorization`	string	Si	`Bearer sk_proj_...`
`Content-Type`	string	Si	`application/json`

Request Body

Campo	Tipo	Requerido	Descripcion
`template_id`	string	Si*	UUID de la plantilla.
`template_internal_id`	number	Si*	ID interno de la plantilla (alternativa a `template_id`).
`recipient_email`	string	Si	Direccion de correo del destinatario.
`sender_email`	string	Si	Direccion de correo del remitente (dominio verificado).
`subject`	string	No	Asunto del correo. Si no se proporciona, se usa el de la plantilla.
`variables`	object	No	Variables para sustitucion en la plantilla.

*Debes enviar template_id O template_internal_id (uno de los dos).

Ejemplo con template UUID

curl -X POST https://api.reallyquickemails.com/v1/send-template-email \
  -H "Authorization: Bearer sk_proj_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipient_email": "nuevo.usuario@ejemplo.com",
    "sender_email": "onboarding@miapp.com",
    "variables": {
      "nombre": "Carlos",
      "plan": "Pro",
      "trial_days": 14,
      "dashboard_url": "https://miapp.com/dashboard"
    }
  }'

Ejemplo con template internal ID

Cada template tiene un ID interno auto-incrementado dentro del proyecto. Util para integraciones que prefieren IDs numericos:

curl -X POST https://api.reallyquickemails.com/v1/send-template-email \
  -H "Authorization: Bearer sk_proj_abc123def456ghi789" \
  -H "Content-Type: application/json" \
  -d '{
    "template_internal_id": 5,
    "recipient_email": "cliente@ejemplo.com",
    "sender_email": "noreply@miapp.com",
    "variables": {
      "nombre": "Maria"
    }
  }'

Respuesta exitosa (200)

{
  "message": "Email sent successfully",
  "email_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "template_id": "550e8400-e29b-41d4-a716-446655440000",
  "template_internal_id": 5,
  "variables_used": ["nombre", "plan", "trial_days", "dashboard_url"],
  "used_cached_html": true
}

Respuesta cuando el destinatario esta suprimido (200)

Si el destinatario se ha dado de baja o ha rebotado, el email se omite automaticamente:

{
  "message": "Email skipped — recipient is suppressed",
  "skipped": true,
  "suppression_reason": "unsubscribed",
  "recipient": "cliente@ejemplo.com"
}

Codigos de Error

Codigo	Descripcion
`400`	`Missing required fields: recipient_email, sender_email, html_body (or template_id)`
`400`	`template_internal_id requires valid project context`
`401`	API Key invalida o no proporcionada.
`404`	Plantilla no encontrada para el proyecto asociado a la API Key.
`500`	Error interno del servidor.

Reply-To Automatico (Inbound Email)

Todos los correos enviados via la API publica incluyen automaticamente un header Reply-To con el nombre del remitente:

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

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

Este comportamiento es automatico y no requiere configuracion. Para recibir notificaciones de respuestas entrantes, configura un webhook de inbound email.

POST /v1/send-batch

Envia correos masivos en un solo request. Ideal para newsletters, promociones y notificaciones a multiples destinatarios. Maximo 12,500 destinatarios por llamada.

Cada destinatario puede tener variables personalizadas a traves del campo data.

Headers

Header	Tipo	Requerido	Descripcion
`Authorization`	string	Si	`Bearer sk_proj_...`
`Content-Type`	string	Si	`application/json`

Request Body

Campo	Tipo	Requerido	Descripcion
`sender`	string	Si	Direccion de correo del remitente (dominio verificado).
`senderName`	string	No	Nombre visible del remitente.
`subject`	string	Si*	Asunto del correo. Requerido si no se usa `templateId`.
`html`	string	Si*	Contenido HTML. Requerido si no se usa `templateId`.
`templateId`	string	Si*	UUID del template. Alternativa a `subject` + `html`.
`email_type`	string	No	Tipo de correo. Default: `"marketing"`.
`scheduled_at`	string	No	Fecha ISO 8601 para envio programado.
`recipients`	array	Si	Lista de destinatarios (maximo 12,500).

*Debes enviar templateId O ambos subject + html.

Estructura de cada recipient:

Campo	Tipo	Requerido	Descripcion
`email`	string	Si	Direccion de correo del destinatario.
`data`	object	No	Variables personalizadas (Handlebars).

Ejemplo con HTML directo

curl -X POST https://api.reallyquickemails.com/v1/send-batch \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "noreply@tudominio.com",
    "senderName": "Mi Empresa",
    "subject": "Oferta especial para ti, {nombre}",
    "html": "<h1>Hola {nombre}!</h1><p>Tenemos una oferta especial en {producto}.</p>",
    "recipients": [
      {
        "email": "juan@ejemplo.com",
        "data": { "nombre": "Juan", "producto": "Plan Pro" }
      },
      {
        "email": "maria@ejemplo.com",
        "data": { "nombre": "Maria", "producto": "Plan Business" }
      }
    ]
  }'

Ejemplo con template

curl -X POST https://api.reallyquickemails.com/v1/send-batch \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "noreply@tudominio.com",
    "senderName": "Mi Empresa",
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "recipients": [
      { "email": "juan@ejemplo.com", "data": { "nombre": "Juan" } },
      { "email": "maria@ejemplo.com", "data": { "nombre": "Maria" } }
    ]
  }'

Ejemplo con envio programado

curl -X POST https://api.reallyquickemails.com/v1/send-batch \
  -H "Authorization: Bearer sk_proj_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "noreply@tudominio.com",
    "subject": "Newsletter semanal",
    "html": "<h1>Newsletter</h1><p>Las noticias de esta semana...</p>",
    "scheduled_at": "2026-03-25T10:00:00Z",
    "recipients": [
      { "email": "sub1@ejemplo.com" },
      { "email": "sub2@ejemplo.com" }
    ]
  }'

Respuesta exitosa (200)

{
  "batch_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "total": 2,
  "queued": 2,
  "scheduled": false,
  "scheduled_for": null,
  "activities": [
    { "email": "juan@ejemplo.com", "activity_id": "uuid-1" },
    { "email": "maria@ejemplo.com", "activity_id": "uuid-2" }
  ]
}

Campo	Tipo	Descripcion
`batch_id`	string	UUID unico del batch para referencia.
`total`	number	Cantidad total de destinatarios.
`queued`	number	Cantidad de emails encolados para envio.
`scheduled`	boolean	`true` si el batch fue programado para envio futuro.
`scheduled_for`	string \| null	Fecha UTC de envio programado, o `null` si es inmediato.
`activities`	array	Lista con `email` y `activity_id` por destinatario para rastreo.

El activity_id de cada destinatario permite rastrear el estado de entrega mediante webhooks.

Codigos de Error

Codigo	Descripcion
`400`	`sender is required`
`400`	`subject or templateId is required`
`400`	`html or templateId is required`
`400`	`recipients array is required and must not be empty`
`400`	`Too many recipients: X. Maximum is 12,500 per batch.`
`400`	`recipients[N].email is required`
`401`	API Key invalida o no proporcionada.
`500`	`Failed to process batch`

Limites

Limite	Valor
Destinatarios por request	12,500
Emails por dia (SES)	106,000
Emails por segundo (SES)	16
Emails por mes (plataforma)	500,000

Tip: Para envios superiores a 12,500 destinatarios, usa multiples llamadas o crea una campana desde el Dashboard de ReallyQuickEmails que maneja automaticamente lotes, rate limiting y reintentos.

APIs de Gestion de Datos

Ademas de los endpoints de envio, la API v1 incluye endpoints para gestionar leads, eventos, tags y atributos. Consulta la documentacion completa en:

Leads API — CRUD de leads, segmentos, tags y atributos
Events API — Tracking de eventos custom desde tus apps

Resumen rapido

Categoria	Endpoint	Descripcion
Leads	`POST /v1/leads`	Crear/actualizar leads (single o bulk hasta 1,000)
	`GET /v1/leads`	Listar con paginacion y filtros
	`GET /v1/leads/:id`	Detalle de un lead con segmentos
	`PUT /v1/leads/:id`	Actualizar lead
	`DELETE /v1/leads/:id`	Eliminar lead
Segmentos	`POST /v1/leads/:id/segments`	Agregar lead a segmentos
	`DELETE /v1/leads/:id/segments/:segmentId`	Quitar de segmento
Tags	`POST /v1/leads/:email/tags`	Agregar tags
	`DELETE /v1/leads/:email/tags`	Quitar tags
	`GET /v1/leads/:email/tags`	Listar tags
Atributos	`POST /v1/leads/:email/attributes`	Set/merge atributos custom
	`GET /v1/leads/:email/attributes`	Obtener atributos
Eventos	`POST /v1/events`	Trackear un evento
	`POST /v1/events/bulk`	Trackear hasta 1,000 eventos
	`GET /v1/events`	Listar eventos con filtros

API Pública v1

On this page