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.
https://mail.sendcorex.com/v3.0/send¿Necesitas enviar a varios destinatarios a la vez? Pasa to como array — consulta Enviar emails en lote.
Parámetros del body
tostring | string[]obligatorioDirección de email del destinatario o array de hasta 50 direcciones.
p. ej.
"user@example.com" or ["a@x.com", "b@x.com"]fromstringobligatorioDirección de email del remitente. Debe pertenecer a un dominio verificado en tu cuenta.
senderNamestringobligatorioNombre que se muestra en la bandeja de entrada del destinatario.
subjectstringobligatorioLínea de asunto del email. Aquí no se admite HTML.
bodystringobligatorioContenido HTML del cuerpo del email.
replyTostringopcionalDirección de respuesta (reply-to). Si se omite, se usa la dirección del remitente.
transactionalbooleanopcionalEstablécelo en true para marcarlo como transaccional. El valor por defecto es false.
attachmentsobject[]opcionalArray de objetos de adjunto. Consulta Enviar adjuntos para ver todos los detalles.
retryRateLimitedintegeropcionalCuá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.
retryUnavailableintegeropcionalCuántas veces reintentar tras un error temporal (0–30). Úsalo con retryUnavailableSeconds (10–3600). Consulta Opciones de entrega para ver todos los detalles.
ignoreHardBouncebooleanopcionalEnví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.
POST /v3.0/send
Authorization: Bearer <api_key>
Idempotency-Key: 3f1c9a52-6b1e-4f0e-9c2a-8d7e5b4a1f00
Content-Type: application/jsonLas 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_PROGRESSconRetry-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.
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"
}codeSiempre SPAM_DETECTED en esta respuesta.
detectionIdIdentificador de esta detección. Inclúyelo al contactar con soporte.
quarantine_idPásalo a /quarantine/release para enviar el email después de revisarlo.
release_instructionsCómo liberar el email.
expires_inCuá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.
Errores
Todos los códigos de error →Los errores devuelven un objeto JSON con error, code y responseTime.
- 401
MISSING_AUTH_HEADERNo hay header Authorization.
- 401
INVALID_API_KEYLa API key no es válida o fue revocada.
- 401
ACCOUNT_BLOCKEDLa cuenta fue bloqueada.
- 401
NO_CREDITS_LEFTNo hay créditos de email suficientes para todos los destinatarios. Cada dirección en to, cc y bcc usa 1 crédito.
- 401
DOMAIN_NOT_VALIDATEDDominio del remitente no verificado.
- 401
LISTED_SPAM_HAUSEl dominio del remitente está listado en Spamhaus.
- 401
ISP_DOMAIN_BLOCKEDNo se permite enviar desde dominios conocidos (gmail.com, outlook.com, etc).
- 401
FROM_HEADER_DOMAIN_MISMATCHDominio del header From no autorizado para este remitente.
- 401
USER_NOT_FOUNDUsuario no encontrado.
- 401
MISSING_USER_PRIVILEGESFaltan privilegios de usuario.
- 401
EMAIL_CREDITS_NOT_FOUNDError al obtener los créditos de email.
- 401
EMAIL_NOT_VALIDATEDEl email de la cuenta aún no fue verificado.
- 429
CREDENTIAL_TEMPORARILY_BLOCKEDAPI key bloqueada temporalmente por violaciones repetidas de la política.
- 429
IP_TEMPORARILY_BLOCKEDIP de la solicitud bloqueada temporalmente por violaciones repetidas de la política.
- 429
TOO_MANY_CONCURRENT_CONNECTIONSDemasiadas solicitudes simultáneas desde esta IP. Inténtalo de nuevo en breve.
- 400
INVALID_JSONEl cuerpo de la solicitud no es un JSON válido.
- 400
MISSING_FROMEl campo from falta o está vacío.
- 400
INVALID_FROM_FORMATEl campo from debe ser una dirección de email válida.
- 400
MISSING_SENDERNAMEEl campo senderName falta o está vacío.
- 400
INVALID_SENDERNAME_FORMATEl campo senderName contiene caracteres no válidos.
- 400
MISSING_SUBJECTEl campo subject falta o está vacío.
- 400
MISSING_BODYEl campo body falta o está vacío.
- 400
MISSING_TOADDRESSEl campo to falta o está vacío.
- 400
MISSING_TOEl campo to falta o está vacío.
- 400
INVALID_TOADDRESSUna o más direcciones de destinatario están mal formadas.
- 400
TOADDRESS_LIMIT_EXCEEDEDMás de 50 destinatarios en el array to.
- 400
INVALID_CCADDRESSUna o más direcciones de cc están mal formadas.
- 400
INVALID_BCCADDRESSUna o más direcciones de bcc están mal formadas.
- 400
RECIPIENT_LIMIT_EXCEEDEDto, cc y bcc juntos tienen más de 50 destinatarios únicos.
- 400
INVALID_SCHEDULED_ATscheduled_at no es una fecha válida o está en el pasado.
- 400
INVALID_SENDER_FORMATEl formato del email del remitente no es válido.
- 400
HEADER_NOT_ALLOWEDLa clave del header personalizado no está en la lista permitida (List-Unsubscribe, List-Id, X-*, etc).
- 400
INVALID_HEADER_VALUEEl valor del header contiene caracteres no válidos (CR/LF no permitidos).
- 400
DANGEROUS_ATTACHMENTUno o más adjuntos fueron bloqueados por motivos de seguridad.
- 400
INVALID_ATTACHMENTEl contenido de un adjunto no es base64 válido.
- 400
MISSING_UNSUBSCRIBE_PLACEHOLDERunsubscribe es true pero el body no tiene placeholder de baja ([unsubscribe_url], [unsubscribe], [unsub_url] o [opt_out_url]).
- 403
ACCOUNT_RESTRICTEDLa cuenta está restringida temporalmente.
- 403
DAILY_LIMITSe alcanzó el límite diario de envío de emails.
- 403
MARKETING_LIMIT_REACHEDSe 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.
- 403
FORBIDDEN_HTML_CONTENTEl 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.
- 403
SPAM_DETECTEDContenido del email marcado como spam. La respuesta incluye el quarantine_id y las instrucciones de liberación.
- 403
SENDER_NAME_MISMATCHSe detectaron varios nombres de remitente para la misma dirección.
- 403
FOLLOWUP_PATTERN_DETECTEDContenido del email marcado como patrón repetido de seguimiento sospechoso.
- 403
SCAM_PATTERN_DETECTEDContenido del email marcado como patrón de estafa.
- 403
ACCOUNT_SUSPENDED_SPOOFINGCuenta suspendida por intentos repetidos de suplantación del header From.
- 409
IDEMPOTENCY_IN_PROGRESSUna solicitud con la misma Idempotency-Key todavía se está procesando. Espera (Retry-After: 1) y reintenta con la misma clave.
- 422
IDEMPOTENCY_KEY_REUSEDEsta Idempotency-Key ya se usó con otro cuerpo. Usa una clave nueva para cada email nuevo.
- 500
INTERNAL_SERVER_ERRORError inesperado del servidor. Inténtalo de nuevo.
- 500
PARSE_ERRORNo se pudo procesar el contenido del email (fallo de parse MIME).
- 500
PERSIST_FAILEDNo se pudo poner el email en cola (fallo de persistencia en la base de datos).
- 503
AUTH_UNAVAILABLENo se pudo validar la API key en este momento. Inténtalo de nuevo.
- 503
UNSUBSCRIBE_UNAVAILABLEServicio de enlace de baja no disponible temporalmente. Inténtalo más tarde.