API Pública v1

La API pública v1 de ReallyQuickEmails (RQE) expone endpoints autenticados mediante Bearer token para integraciones externas.

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

Autenticacion

Todos los endpoints de la API pública requieren autenticación mediante Bearer token con una clave del proyecto:

Authorization: Bearer sk_proj_xxxxxxxxxxxx

Se aceptan tres prefijos de clave:

Las claves se generan desde el panel de administración del proyecto. Si la clave es inválida o no se proporciona, el servidor responde con 401 Unauthorized. Todos los requests con body requieren además el header Content-Type: application/json.

Respuesta de error de autenticacion

{
  "error": "Missing or invalid API key. Use: Authorization: Bearer sk_proj_..."
}

Si la clave tiene un prefijo válido pero no corresponde a ningún proyecto, la respuesta es:

{
  "error": "Invalid API key"
}

POST /v1/send-email

Envía un email individual a hasta 50 destinatarios.

Request Body

El tracking de aperturas y clics se aplica en segundo plano (los remitentes en modo transaccional omiten el tracking). Este endpoint no agrega footer de unsubscribe ni headers List-Unsubscribe — esos se agregan automáticamente en campañas y en /v1/send-template-email; en /v1/send-batch puedes pasarlos mediante custom_headers.

Ejemplo simple

curl -X POST https://api.reallyquickemails.com/v1/send-email \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -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_xxxxxxxxxxxx" \
  -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"
}

email_id es el ID de actividad del envío — úsalo para correlacionar los eventos que llegan a tus webhooks. Puede ser null si el registro de actividad no pudo crearse.

Supresión: la verificación de supresión ocurre al procesar el envío en segundo plano. Si el destinatario está suprimido (rebote, queja o baja), el email no se envía y la actividad queda con estado suppressed. Este endpoint no devuelve una respuesta skipped síncrona — /v1/send-template-email sí verifica la supresión antes de responder.

Codigos de Error

¿Necesitas envío programado, dry_run o plantillas en envíos individuales? Ver más en API avanzada de envío.

POST /v1/send-template-email

Envía un correo utilizando una plantilla pre-configurada con sustitución de variables (soporta loops {{#each}}).

Request Body

*Debes enviar template_id O template_internal_id. Si no envías ninguno, html_body (junto con recipient_email y sender_email) es requerido.

Este endpoint agrega automáticamente:

• Un footer de cancelación de suscripción si el HTML no incluye la URL de unsubscribe.
• Los headers List-Unsubscribe y List-Unsubscribe-Post (RFC 8058).
• Las variables view_in_browser_url y unsubscribe_url (si no las envías tú).

Las respuestas del destinatario se enrutan a la bandeja del remitente — ver Reply-To Automático.

Ejemplo con template UUID

curl -X POST https://api.reallyquickemails.com/v1/send-template-email \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -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. Útil para integraciones que prefieren IDs numéricos:

curl -X POST https://api.reallyquickemails.com/v1/send-template-email \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -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": null,
  "variables_used": ["nombre", "plan", "trial_days", "dashboard_url", "view_in_browser_url", "unsubscribe_url"],
  "used_cached_html": true
}

variables_used incluye también las variables inyectadas automáticamente (view_in_browser_url, unsubscribe_url). used_cached_html es true cuando se usó el HTML pre-renderizado de la plantilla.

Respuesta cuando el destinatario esta suprimido (200)

Si el destinatario se ha dado de baja o ha rebotado, el email se omite automáticamente:

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

Codigos de Error

Ver más en Plantillas.

POST /v1/send-batch

Envía correos masivos en un solo request — hasta 10,000 destinatarios por llamada.

Request Body

*Debes enviar templateId O ambos subject + html.

Estructura de cada recipient:

Headers

Ejemplo con HTML directo

curl -X POST https://api.reallyquickemails.com/v1/send-batch \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -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" }
      }
    ]
  }'

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

const { data, error } = await rqe.emails.sendBatch({
  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' } },
  ],
});

if (error) console.error(error);
else console.log('Batch encolado:', data.batch_id);

Ejemplo con template

curl -X POST https://api.reallyquickemails.com/v1/send-batch \
  -H "Authorization: Bearer sk_proj_xxxxxxxxxxxx" \
  -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" } }
    ]
  }'

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

await rqe.emails.sendBatch({
  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_xxxxxxxxxxxx" \
  -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" }
    ]
  }'

import { RQE } from '@reallyquickemails/sdk';

const rqe = new RQE({ apiKey: process.env.RQE_API_KEY });

await rqe.emails.sendBatch({
  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" }
  ]
}

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

Supresión: igual que en /v1/send-email, la supresión se aplica al procesar cada envío en segundo plano — los destinatarios suprimidos se omiten y su actividad queda con estado suppressed.

Idempotencia

Envía el header opcional Idempotency-Key (1–256 caracteres) para evitar envíos duplicados ante reintentos. Las respuestas con status 2xx o 4xx se cachean por 24 horas, con alcance por proyecto. Si repites la misma clave dentro de ese plazo, recibes la respuesta cacheada sin re-procesar el batch, junto con el header Idempotency-Replayed: true.

En el SDK de Node.js, pasa { idempotencyKey } como segundo argumento de rqe.emails.sendBatch(params, { idempotencyKey }). Ver más en SDK de Node.js.

Dry run

Con "dry_run": true la API devuelve una previsualización sin encolar emails ni crear registros de actividad:

{
  "dry_run": true,
  "test_mode": false,
  "recipients_count": 2,
  "would_send": {
    "template_id": null,
    "subject": "Oferta especial para ti, {nombre}",
    "from": "Mi Empresa <noreply@tudominio.com>",
    "first_recipient": "juan@ejemplo.com"
  }
}

Limites

Tip: Para envíos superiores a 10,000 destinatarios, usa múltiples llamadas o crea una campaña desde el Dashboard de RQE, que maneja automáticamente lotes y reintentos. Ver más en Campañas.

Codigos de Error

Reply-To Automatico (Inbound Email)

Los correos enviados vía /v1/send-email y /v1/send-batch incluyen automáticamente 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 dirección técnica. Cuando el destinatario responde, la respuesta se enruta automáticamente a RQE y se asocia al hilo de conversación original.

Este comportamiento es automático y no requiere configuración. Para recibir notificaciones de respuestas entrantes, configura un webhook de inbound email.

En /v1/send-template-email las respuestas van directo a la bandeja del remitente: el Reply-To usa la dirección de respuesta configurada en el perfil del remitente, o el propio sender_email si no hay una.

APIs de Gestion de Datos

Además de los endpoints de envío, la API v1 incluye endpoints para gestionar leads, eventos, tags y atributos. Consulta la documentación completa en:

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

Resumen rapido