Email

Enviar email

Envía un email transaccional o de marketing a uno o varios destinatarios. Admite cuerpos HTML, adjuntos, reply-to y headers de marketing.

POSThttps://mail.sendcorex.com/v3.0/send
i

¿Necesitas enviar a varios destinatarios a la vez? Pasa to como array — consulta Enviar emails en lote.

Parámetros del body

  • tostring | string[]obligatorio

    Dirección de email del destinatario o array de hasta 50 direcciones.

    p. ej. "user@example.com" or ["a@x.com", "b@x.com"]

  • fromstringobligatorio

    Dirección de email del remitente. Debe pertenecer a un dominio verificado en tu cuenta.

  • senderNamestringobligatorio

    Nombre que se muestra en la bandeja de entrada del destinatario.

  • subjectstringobligatorio

    Línea de asunto del email. Aquí no se admite HTML.

  • bodystringobligatorio

    Contenido HTML del cuerpo del email.

  • replyTostringopcional

    Dirección de respuesta (reply-to). Si se omite, se usa la dirección del remitente.

  • transactionalbooleanopcional

    Establécelo en true para marcarlo como transaccional. El valor por defecto es false.

  • attachmentsobject[]opcional

    Array de objetos de adjunto. Consulta Enviar adjuntos para ver todos los detalles.

  • retryRateLimitedintegeropcional

    Cuántos ciclos de 30 minutos seguir intentando cuando el proveedor te aplica rate limit (0–24, por defecto 25). Consulta Opciones de entrega para ver todos los detalles.

  • retryUnavailableintegeropcional

    Cuántas veces reintentar tras un error temporal (0–30). Úsalo con retryUnavailableSeconds (10–3600). Consulta Opciones de entrega para ver todos los detalles.

  • ignoreHardBouncebooleanopcional

    Envía aunque la dirección haya dado hard bounce en los últimos 90 días. El valor por defecto es false. Consulta Opciones de entrega para ver todos los detalles.

Inicio rápido

import axios from 'axios';

const response = await axios.post(
  'https://mail.sendcorex.com/v3.0/send',
  {
    to: 'user@example.com',
    from: 'noreply@yourdomain.com',
    senderName: 'My App',
    subject: 'Welcome aboard!',
    body: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
    replyTo: 'support@yourdomain.com',
  },
  {
    headers: { Authorization: process.env.SENDCOREX_API_KEY },
  }
);

const { id, ids, recipients } = response.data;

Respuesta

{
  "success": true,
  "message": "Email queued successfully",
  "code": "EMAIL_QUEUED_SUCCESS",
  "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
  "ids": [
    { "id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f", "recipient": "user@example.com" }
  ],
  "recipients": 1,
  "scheduledAt": null
}

Solicitudes idempotentes

Envía la cabecera Idempotency-Key con cualquier valor único (recomendamos un UUID v4) para reintentar POST /v3.0/send de forma segura. Si la conexión se corta o hay un timeout, reintenta con la misma clave y el mismo cuerpo: devolvemos la respuesta original (mismo id de email) y el email no se envía dos veces.

HTTP
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/json
  • Las claves valen 24 horas y son exclusivas de tu cuenta.

  • Caracteres permitidos: letras, números, _ - : . (1–255 caracteres).

  • Una respuesta repetida trae la cabecera Idempotent-Replayed: true.

  • Usa una clave nueva para cada email nuevo. Reutilizar una clave con otro cuerpo devuelve 422 IDEMPOTENCY_KEY_REUSED.

  • Si la primera solicitud todavía se está procesando, recibes 409 IDEMPOTENCY_IN_PROGRESS con Retry-After: 1. Espera y reintenta con la misma clave.

  • Los errores del servidor (5xx) y los límites de tasa (429) no se guardan: reintentar con la misma clave envía normalmente.

  • Sin la cabecera, el endpoint funciona como antes.

↻

Reintento recomendado: ante error de red, timeout, 409, 429 o 5xx, reintenta con la misma clave usando backoff exponencial (1 s, 2 s, 4 s…, hasta 5 intentos).

Ejemplo: clave UUID + reintento con backoff

import { randomUUID } from 'node:crypto';

const RETRY_STATUS = new Set([409, 429, 500, 502, 503, 504]);
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function sendEmail(email) {
  const key = randomUUID(); // one key per email, reused on every retry
  const body = JSON.stringify(email); // same body on every retry

  for (let attempt = 1; attempt <= 5; attempt++) {
    try {
      const res = await fetch('https://mail.sendcorex.com/v3.0/send', {
        method: 'POST',
        headers: {
          Authorization: process.env.SENDCOREX_API_KEY,
          'Idempotency-Key': key,
          'Content-Type': 'application/json',
        },
        body,
        signal: AbortSignal.timeout(15_000),
      });

      if (!RETRY_STATUS.has(res.status)) {
        const data = await res.json();
        if (!res.ok) throw new Error(data.code || 'SEND_FAILED');
        // Idempotent-Replayed: true → this is the original response (not sent twice)
        return { ...data, replayed: res.headers.get('Idempotent-Replayed') === 'true' };
      }
      if (attempt === 5) throw new Error('HTTP ' + res.status);
      const retryAfter = Number(res.headers.get('Retry-After')) * 1000;
      await sleep(retryAfter || 1000 * 2 ** (attempt - 1));
    } catch (err) {
      // network error or timeout: retry with the same key
      if (err.message?.startsWith('HTTP ') || attempt === 5 || (err.name !== 'TypeError' && err.name !== 'TimeoutError')) throw err;
      await sleep(1000 * 2 ** (attempt - 1));
    }
  }
}

const result = await sendEmail({
  to: 'user@example.com',
  from: 'noreply@yourdomain.com',
  senderName: 'My App',
  subject: 'Your receipt',
  body: '<p>Thanks for your order.</p>',
});
console.log(result.id, result.replayed);

Mis mensajes se marcan como spam

Cada mensaje pasa por nuestro filtro anti-spam. Cuando uno se marca, la solicitud devuelve 403 con el código SPAM_DETECTED y el email queda retenido en cuarentena.

403

Marcado como spam

{
  "error": "Email content flagged as spam.",
  "code": "SPAM_DETECTED",
  "detectionId": "9c1e5a7d-2b4f-4e8a-a6d3-0f1b2c3d4e5f",
  "quarantine_id": "qtn_3f2a1b4c8e9d4f7a",
  "release_instructions": "POST /v3.0/quarantine/release with { quarantine_id }",
  "expires_in": "3 hours"
}
  • code

    Siempre SPAM_DETECTED en esta respuesta.

  • detectionId

    Identificador de esta detección. Inclúyelo al contactar con soporte.

  • quarantine_id

    Pásalo a /quarantine/release para enviar el email después de revisarlo.

  • release_instructions

    Cómo liberar el email.

  • expires_in

    Cuánto tiempo se conserva el registro de cuarentena antes de expirar.

!

Un email en cuarentena no se entrega. Usa /quarantine/release para enviarlo después de revisarlo. El registro de cuarentena expira a las 3 horas.

Si quarantine_id, release_instructions y expires_in vuelven como null, el email se bloqueó sin registro de cuarentena. No se puede liberar: corrige el contenido y vuelve a enviarlo.

Los errores devuelven un objeto JSON con error, code y responseTime.

  • 401MISSING_AUTH_HEADER

    No hay header Authorization.

  • 401INVALID_API_KEY

    La API key no es válida o fue revocada.

  • 401ACCOUNT_BLOCKED

    La cuenta fue bloqueada.

  • 401NO_CREDITS_LEFT

    No hay créditos de email suficientes para todos los destinatarios. Cada dirección en to, cc y bcc usa 1 crédito.

  • 401DOMAIN_NOT_VALIDATED

    Dominio del remitente no verificado.

  • 401LISTED_SPAM_HAUS

    El dominio del remitente está listado en Spamhaus.

  • 401ISP_DOMAIN_BLOCKED

    No se permite enviar desde dominios conocidos (gmail.com, outlook.com, etc).

  • 401FROM_HEADER_DOMAIN_MISMATCH

    Dominio del header From no autorizado para este remitente.

  • 401USER_NOT_FOUND

    Usuario no encontrado.

  • 401MISSING_USER_PRIVILEGES

    Faltan privilegios de usuario.

  • 401EMAIL_CREDITS_NOT_FOUND

    Error al obtener los créditos de email.

  • 401EMAIL_NOT_VALIDATED

    El email de la cuenta aún no fue verificado.

  • 429CREDENTIAL_TEMPORARILY_BLOCKED

    API key bloqueada temporalmente por violaciones repetidas de la política.

  • 429IP_TEMPORARILY_BLOCKED

    IP de la solicitud bloqueada temporalmente por violaciones repetidas de la política.

  • 429TOO_MANY_CONCURRENT_CONNECTIONS

    Demasiadas solicitudes simultáneas desde esta IP. Inténtalo de nuevo en breve.

  • 400INVALID_JSON

    El cuerpo de la solicitud no es un JSON válido.

  • 400MISSING_FROM

    El campo from falta o está vacío.

  • 400INVALID_FROM_FORMAT

    El campo from debe ser una dirección de email válida.

  • 400MISSING_SENDERNAME

    El campo senderName falta o está vacío.

  • 400INVALID_SENDERNAME_FORMAT

    El campo senderName contiene caracteres no válidos.

  • 400MISSING_SUBJECT

    El campo subject falta o está vacío.

  • 400MISSING_BODY

    El campo body falta o está vacío.

  • 400MISSING_TOADDRESS

    El campo to falta o está vacío.

  • 400MISSING_TO

    El campo to falta o está vacío.

  • 400INVALID_TOADDRESS

    Una o más direcciones de destinatario están mal formadas.

  • 400TOADDRESS_LIMIT_EXCEEDED

    Más de 50 destinatarios en el array to.

  • 400INVALID_CCADDRESS

    Una o más direcciones de cc están mal formadas.

  • 400INVALID_BCCADDRESS

    Una o más direcciones de bcc están mal formadas.

  • 400RECIPIENT_LIMIT_EXCEEDED

    to, cc y bcc juntos tienen más de 50 destinatarios únicos.

  • 400INVALID_SCHEDULED_AT

    scheduled_at no es una fecha válida o está en el pasado.

  • 400INVALID_SENDER_FORMAT

    El formato del email del remitente no es válido.

  • 400HEADER_NOT_ALLOWED

    La clave del header personalizado no está en la lista permitida (List-Unsubscribe, List-Id, X-*, etc).

  • 400INVALID_HEADER_VALUE

    El valor del header contiene caracteres no válidos (CR/LF no permitidos).

  • 400DANGEROUS_ATTACHMENT

    Uno o más adjuntos fueron bloqueados por motivos de seguridad.

  • 400INVALID_ATTACHMENT

    El contenido de un adjunto no es base64 válido.

  • 400MISSING_UNSUBSCRIBE_PLACEHOLDER

    unsubscribe es true pero el body no tiene placeholder de baja ([unsubscribe_url], [unsubscribe], [unsub_url] o [opt_out_url]).

  • 403ACCOUNT_RESTRICTED

    La cuenta está restringida temporalmente.

  • 403DAILY_LIMIT

    Se alcanzó el límite diario de envío de emails.

  • 403MARKETING_LIMIT_REACHED

    Se alcanzó el límite diario de marketing del plan gratuito: 30 emails de marketing o cold outreach por día, contados por destinatario en una ventana móvil de 24 horas. La respuesta incluye limit, used, recipients y upgradeUrl. Los emails transaccionales se siguen enviando; nada queda en cola.

  • 403FORBIDDEN_HTML_CONTENT

    El HTML contiene contenido activo no permitido en emails (script, iframe, form, input, button, embed, object, svg, handlers on*, enlaces javascript:, meta refresh…). La respuesta lista lo encontrado. Usa un <a> con estilos en lugar de botones o formularios.

  • 403SPAM_DETECTED

    Contenido del email marcado como spam. La respuesta incluye el quarantine_id y las instrucciones de liberación.

  • 403SENDER_NAME_MISMATCH

    Se detectaron varios nombres de remitente para la misma dirección.

  • 403FOLLOWUP_PATTERN_DETECTED

    Contenido del email marcado como patrón repetido de seguimiento sospechoso.

  • 403SCAM_PATTERN_DETECTED

    Contenido del email marcado como patrón de estafa.

  • 403ACCOUNT_SUSPENDED_SPOOFING

    Cuenta suspendida por intentos repetidos de suplantación del header From.

  • 409IDEMPOTENCY_IN_PROGRESS

    Una solicitud con la misma Idempotency-Key todavía se está procesando. Espera (Retry-After: 1) y reintenta con la misma clave.

  • 422IDEMPOTENCY_KEY_REUSED

    Esta Idempotency-Key ya se usó con otro cuerpo. Usa una clave nueva para cada email nuevo.

  • 500INTERNAL_SERVER_ERROR

    Error inesperado del servidor. Inténtalo de nuevo.

  • 500PARSE_ERROR

    No se pudo procesar el contenido del email (fallo de parse MIME).

  • 500PERSIST_FAILED

    No se pudo poner el email en cola (fallo de persistencia en la base de datos).

  • 503AUTH_UNAVAILABLE

    No se pudo validar la API key en este momento. Inténtalo de nuevo.

  • 503UNSUBSCRIBE_UNAVAILABLE

    Servicio de enlace de baja no disponible temporalmente. Inténtalo más tarde.