Headers de baja
Añade headers List-Unsubscribe a tus emails para que los destinatarios (y proveedores como Gmail y Yahoo) puedan darse de baja sin marcar tu email como spam. Esto mejora mucho la entregabilidad en envíos masivos y de marketing.
https://mail.sendcorex.com/v3.0/sendLos proveedores de correo recomiendan encarecidamente (y en algunos casos exigen) List-Unsubscribe en cualquier envío masivo. Si falta este header en envíos de gran volumen, puede perjudicar la llegada a la bandeja de entrada.
Los headers van en el objeto headers de la solicitud de envío. Para las reglas de nombres que se aplican a los demás headers, consultaHeaders personalizados.
Headers admitidos
List-UnsubscribeopcionalLista de métodos de baja separados por comas, entre corchetes angulares. Admite un enlace mailto: y uno https:.
p. ej.
"<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>"List-Unsubscribe-PostopcionalActiva la baja con un clic de Gmail/Yahoo. Obligatorio si quieres que el botón "Cancelar suscripción" aparezca directamente en la interfaz de la bandeja de entrada. Debe ser exactamente:
p. ej.
"List-Unsubscribe=One-Click"List-IdopcionalIdentifica la lista de correo a la que pertenece este email.
p. ej.
"My List <mylist.yourdomain.com>"
Enlace de baja automático
Si no tienes tu propio sistema de bajas, Sendcorex puede generar y gestionar el enlace de baja y el mailto por ti. Establece unsubscribe: true en la solicitud de envío e incluye uno de los placeholders admitidos en el cuerpo, donde quieras insertar el enlace.
Placeholders admitidos
[unsubscribe_url][unsubscribe][unsub_url][opt_out_url]
Usa cualquiera de ellos dentro de un href (o en cualquier parte del cuerpo). Sendcorex lo reemplaza por el enlace de baja real de cada destinatario antes de enviar.
unsubscribe: true, sin sistema propio
{
"to": "contact@gmail.com",
"from": "noreply@yourdomain.com",
"senderName": "My App",
"subject": "Welcome aboard!",
"body": "<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
"replyTo": "support@yourdomain.com",
"unsubscribe": true
}Si se establece unsubscribe: true pero no se encuentra ninguno de los placeholders admitidos en el cuerpo, la solicitud falla con MISSING_UNSUBSCRIBE_PLACEHOLDER. Consulta larespuesta 400.
Lista de contactos
opcionalcontact_list no es obligatorio. Solo controla en qué lista se guarda el destinatario, para seguimiento y organización. No tiene nada que ver con el enlace de baja.
Sin contact_list (por defecto)
El contacto se guarda automáticamente en una lista por defecto llamada "API Contacts". Este nombre no se puede cambiar. Puedes consultarla cuando quieras en tuslistas de contactos.
{
"to": "contact@gmail.com",
"from": "noreply@yourdomain.com",
"subject": "Welcome aboard!",
"body": "<h1>Welcome!</h1><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
"unsubscribe": true
}Con contact_list (nombre personalizado)
Si la lista todavía no existe, se crea automáticamente. Es útil para separar audiencias, por ejemplo una lista por campaña o plataforma.
"CRM 2026 - Gmail""Newsletter - Trial Users""Support Tickets"
{
"to": "contact@gmail.com",
"from": "noreply@yourdomain.com",
"subject": "Welcome aboard!",
"body": "<h1>Welcome!</h1><p><a href=\"[unsubscribe]\">Unsubscribe</a></p>",
"unsubscribe": true,
"contact_list": "CRM 2026 - Gmail"
}Inicio rápido
import axios from 'axios';
const response = await axios.post(
'https://mail.sendcorex.com/v3.0/send',
{
to: 'contact@gmail.com',
from: 'noreply@yourdomain.com',
senderName: 'My App',
subject: 'Welcome aboard!',
body: '<h1>Welcome!</h1><p>Thanks for signing up.</p><p><a href="[unsubscribe]">Unsubscribe</a></p>',
unsubscribe: true,
contact_list: 'CRM 2026 - Gmail',
headers: {
'List-Id': 'My List <mylist.yourdomain.com>',
'List-Unsubscribe':
'<mailto:unsubscribe@yourdomain.com?subject=unsubscribe>,<https://yourdomain.com/unsubscribe?u=123>',
'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
},
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } }
);
const { id } = response.data;Respuesta
{
"success": true,
"message": "Email queued successfully",
"code": "EMAIL_QUEUED_SUCCESS",
"id": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f"
}Errores
Todos los códigos de error →Los errores devuelven un objeto JSON con error y code.
- 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.