API Keys

ReallyQuickEmails utiliza Secret Keys con prefijo para autenticar todas las solicitudes a la API. Cada proyecto tiene dos keys distintas: una para tráfico productivo (Live) y otra para desarrollo (Test).

Live vs Test

sk_proj_* y sk_live_* funcionan idéntico — ambos son modo live y son válidos indefinidamente.

Comportamiento detallado de Test Mode

Las keys sk_test_* te permiten desarrollar e iterar sin contaminar tus métricas productivas:

• Envíos reales: el email llega al inbox del destinatario igual que en live. Esto es deliberado para que pruebes deliverability, render visual y comportamiento de los clientes de email.
• Consume cuota mensual: como el envío es real, cuenta contra el límite mensual del plan igual que un envío live.
• Activity con is_test=true: cada envío queda registrado en Activity con la flag is_test: true. El dashboard filtra estos registros automáticamente cuando el toggle Live/Test está en modo Live.
• Webhooks separados: tanto los eventos outbound (email.delivery, email.bounce, email.open, email.click) como los inbound replies se enrutan a las URLs *_dev. Si la URL _dev no está configurada, el evento simplemente no se entrega — no se hace fallback al webhook_url de live.
• Toggle en dashboard: el sidebar tiene un switch global Live/Test que filtra Activity, Campaigns y métricas según el modo seleccionado.

Ver Modos Live y Test para el detalle completo del routing de webhooks y casos extremos.

Donde encontrar tus Secret Keys

1. Ingresa al dashboard de RQE.
2. Navega al proyecto donde deseas obtener las credenciales.
3. En el menú lateral, abre Integraciones → API Keys.
4. Ahí encontrarás:
   • Producción (Live) — sk_live_* o sk_proj_*.
   • Test — sk_test_*. Generable/regenerable independientemente de la live.

Cada key tiene controles separados de mostrar/copiar/regenerar. Regenerar la live no afecta la test, y viceversa.

Uso

Pasa la key como Bearer token en el header Authorization:

Authorization: Bearer sk_live_tu_secret_key

# Live
curl -X POST https://api.reallyquickemails.com/v1/send-email \
  -H "Authorization: Bearer sk_live_tu_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": "destinatario@ejemplo.com",
    "sender_email": "noreply@tudominio.com",
    "subject": "Hola",
    "html_body": "<h1>Hola!</h1>"
  }'

# Test (mismo endpoint, solo cambia el prefijo de la key)
curl -X POST https://api.reallyquickemails.com/v1/send-email \
  -H "Authorization: Bearer sk_test_tu_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_email": "qa@tudominio.com",
    "sender_email": "noreply@tudominio.com",
    "subject": "Smoke test",
    "html_body": "<p>Test desde staging</p>"
  }'

Importante: todos los endpoints de la API aceptan keys live y test. RQE determina el modo del envío únicamente por el prefijo de la key — no existe un parámetro mode ni headers especiales para forzar un modo distinto.

Errores de prefijo inválido

Si pasas una key con un prefijo desconocido (ej. sk_dev_), recibes 401 Unauthorized:

{ "error": "Invalid API key prefix. Expected sk_proj_*, sk_live_* or sk_test_*." }

Idempotency

Los endpoints POST /send-email (API avanzada) y POST /v1/send-batch soportan idempotencia opcional vía header Idempotency-Key:

Idempotency-Key: pedido-12345-confirmacion

• La key es un string arbitrario de 1 a 256 caracteres.
• La respuesta del primer request se cachea por 24 horas, scoped a (project_id, idempotency_key).
• Si llega otro request con la misma key dentro de la ventana, RQE devuelve la respuesta cacheada del primer request, con header Idempotency-Replayed: true.
• Las respuestas 5xx no se cachean — puedes reintentar con la misma key.
• Útil para retries de red sin riesgo de doble envío. Funciona idéntico en live y test.

POST /v1/send-email y POST /v1/send-template-email no soportan Idempotency-Key. Si necesitas idempotencia en envíos individuales, usa la API avanzada.

Dry Run

Para validar payload y variables sin enviar el email, usa POST /send-email (API avanzada, campos recipient/sender/html) con dry_run: true en el body:

curl -X POST https://api.reallyquickemails.com/send-email \
  -H "Authorization: Bearer sk_test_tu_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "destinatario@ejemplo.com",
    "sender": "noreply@tudominio.com",
    "subject": "Hola {{nombre}}",
    "html": "<h1>Hola {{nombre}}</h1>",
    "data": { "nombre": "María" },
    "dry_run": true
  }'

Respuesta:

{
  "dry_run": true,
  "test_mode": true,
  "sample_cart_items_injected": false,
  "would_send": {
    "to": ["destinatario@ejemplo.com"],
    "cc": [],
    "bcc": [],
    "from": "noreply@tudominio.com",
    "subject": "Hola María",
    "html_preview": "<h1>Hola María</h1>",
    "template_id": null,
    "variables_used": ["nombre"]
  }
}

No se envía nada, no se encola, no se registra actividad ni consume cuota. Útil para CI o para validar templates antes de un envío masivo. dry_run no está disponible en /v1/send-email. Ver detalles del dry run.

Seguridad

• Nunca expongas tus Secret Keys en código del lado del cliente (frontend, apps móviles, repos públicos). Las keys deben usarse exclusivamente desde backend.
• Variables de entorno — almacena en .env, nunca hardcodeadas:

# .env
RQE_LIVE_KEY=sk_live_tu_secret_key
RQE_TEST_KEY=sk_test_tu_test_key

// Ejemplo Node.js — usar la key correcta según el ambiente
const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.RQE_LIVE_KEY
  : process.env.RQE_TEST_KEY;

const response = await fetch("https://api.reallyquickemails.com/v1/send-email", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    recipient_email: "cliente@ejemplo.com",
    sender_email: "noreply@tudominio.com",
    subject: "Hola",
    html_body: "<h1>Hola!</h1>",
  }),
});

• Rota tus keys periódicamente. Si sospechas que una fue comprometida, regenera desde el dashboard inmediatamente. La key anterior queda invalidada en el momento.
• Agrega .env a tu .gitignore para evitar que las credenciales se suban al repositorio.
• Mantén live y test aisladas entre ambientes. Pasar accidentalmente la sk_live_* en staging puede contaminar métricas y consumir cuota.