Saltar al contenido
Correo Invensys

Guía de integración

Todo lo necesario para que tu sistema envíe facturas, pedidos y avisos por correo con la API de Correo Invensys. Los detalles de cada endpoint están en la referencia de la API.

Para probar usa una llave de prueba (empieza con xrs_test_): pasa por las mismas validaciones, pero nada se envía de verdad, no cuenta para tu plan y los resultados son simulados. Pídela a Invensys o genérala en el portal (Apps y llaves).

Inicio rápido#

Tu primer correo en 5 minutos, sin enviar nada de verdad, con el modo de prueba.

  1. Consigue una llave de prueba. Empieza con xrs_test_. Te la da Invensys o la genera quien administra tu cuenta en el portal (Apps y llaves → Llave de prueba). Se muestra una sola vez.
  2. Guárdala en una variable de entorno, nunca en el código:

bash export XRSEND_API_KEY="xrs_test_..."

  1. Ten a la mano la clave de tu negocio (por ejemplo ferreteria-lopez): te la damos al darlo de alta y va en el campo negocio de cada correo.
  2. Envía un correo a entregado@prueba.xr-send.com:
ejemplos/curl/primer-correo.sh
#!/bin/sh
# Primer correo con la llave de PRUEBA (xrs_test_…): nada se envía de verdad.
# export XRSEND_API_KEY="xrs_test_..."   (nunca la pongas en el código)
URL="${XRSEND_URL:-https://api.xr-send.com}"
NEGOCIO="${XRSEND_NEGOCIO:-ferreteria-lopez}"

curl -sS -X POST "$URL/v1/correos" \
  -H "X-API-Key: $XRSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "negocio": "'"$NEGOCIO"'",
    "tipo": "notificacion",
    "para": "entregado@prueba.xr-send.com",
    "asunto": "Mi primer correo",
    "texto": "Hola, esto es una prueba."
  }'
# Respuesta 202: {"id": "…", "estado": "en_cola", …, "prueba": true}

5. Lee la respuesta. Un 202 es éxito; guarda el id:

{"id": "9c5272e5-85dd-4504-af8b-2747c3229180", "estado": "en_cola", "destinatarios": 1,
 "omitidos": [], "corregidos": [], "duplicado": false, "aviso": null,
 "uso_dia": {"usados": 0, "limite": 500}, "prueba": true}

"prueba": true confirma que fue simulado: no salió ningún correo y uso_dia no aumentó.

6. Consulta cómo le fue con GET /v1/correos/{id} (ver Estados de entrega). En modo de prueba el resultado se aplica al instante: este correo ya aparece entregado.

Prueba también rebote@prueba.xr-send.com, spam@prueba.xr-send.com y retraso@prueba.xr-send.com para ver cómo responde tu sistema cuando algo sale mal (ver Autenticación y llaves).

Cuando todo funcione, cambia la variable por tu llave de producción (empieza con xr_). No cambia nada más: misma URL, mismos campos, mismas respuestas (sin "prueba").

Autenticación y llaves#

La API está en https://api.xr-send.com. Cada petición lleva la llave de tu sistema en el header X-API-Key:

X-API-Key: xrs_test_...
Content-Type: application/json

Cada sistema (app) que envía correos tiene dos llaves:

Llave de producción Llave de prueba
Empieza con xr_ xrs_test_
Envía correos Sí, de verdad No: el resultado es simulado
Cuenta para el plan y la reputación Sí No
Agrega direcciones a la lista de bloqueadas Sí (rebotes y quejas reales) No
Avisa a tus webhooks Sí Sí, marcados como prueba

Las dos se muestran una sola vez al crearlas o rotarlas: guárdalas en el vault o en variables de entorno de tu servidor (XRSEND_API_KEY), nunca en el código ni en el navegador. Si una se filtra, pide rotarla: la anterior deja de funcionar en ese momento.

El modo de prueba#

Con la llave de prueba, la petición pasa por las mismas validaciones que una real: direcciones mal escritas, dominios con error (@gmial.com), direcciones bloqueadas, duplicados, negocio suspendido, límite del plan, tamaño de adjuntos. La respuesta tiene la misma forma, más "prueba": true. Pero:

  • nunca se envía nada, a ninguna dirección;
  • no cuenta para el plan, el uso del mes, la reputación ni los reportes;
  • un rebote o una queja de prueba no bloquea la dirección.

El resultado lo decide la dirección, en el dominio reservado prueba.xr-send.com:

Dirección Resultado simulado Aviso a tu webhook
entregado@prueba.xr-send.com entregado entregado
rebote@prueba.xr-send.com rebotado (la dirección «no existe») rebotado
spam@prueba.xr-send.com queja (lo «marcó como spam») queja
retraso@prueba.xr-send.com demorado demorado
bloqueado@prueba.xr-send.com se omite, como una dirección bloqueada (sale en omitidos) no_enviado
cualquier otra dirección entregado (simulado: no se le envía nada) entregado

Puedes agregar +algo antes de la @ (rebote+fac123@prueba.xr-send.com) para distinguir tus pruebas.

Con la llave de prueba:

  • GET /v1/correos y GET /v1/correos/{id} muestran solo los correos de prueba (y la de producción, solo los reales);
  • el resumen, el reporte de entregas, el uso y la lista de bloqueadas muestran los datos reales del negocio (los de prueba nunca cuentan);
  • puedes consultar tus webhooks y mandarles un aviso de prueba, pero registrarlos, cambiarlos o borrarlos se hace con la llave de producción o en el portal (403 con la de prueba);
  • hay un tope de 1,000 correos de prueba por hora por app (429 con "prueba": true si lo pasas).

Tu llave de prueba la genera, rota o revoca Invensys o quien administra tu cuenta en el portal.

Enviar un correo#

POST /v1/correos acepta el correo y lo pone en cola; sale segundos después y los reintentos hacia el servidor de correo los hacemos nosotros.

ejemplos/curl/enviar.sh
#!/bin/sh
# Enviar una factura con PDF adjunto, copia y folio (referencia).
# Con "reenvio": true se reenvía a propósito aunque sea el mismo correo de hace menos de 2 min.
URL="${XRSEND_URL:-https://api.xr-send.com}"
NEGOCIO="${XRSEND_NEGOCIO:-ferreteria-lopez}"
PDF_B64=$(printf '%%PDF-1.4\n%% factura de ejemplo\n' | base64 | tr -d '\n')   # o: base64 < FAC-1234.pdf

curl -sS -X POST "$URL/v1/correos" \
  -H "X-API-Key: $XRSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "negocio": "'"$NEGOCIO"'",
    "tipo": "factura",
    "para": "Cliente Ejemplo <entregado@prueba.xr-send.com>",
    "cc": ["contador@gamil.com"],
    "asunto": "Tu factura FAC-1234",
    "texto": "Adjuntamos tu factura FAC-1234.",
    "html": "<p>Adjuntamos tu factura <b>FAC-1234</b>.</p>",
    "referencia": "FAC-1234",
    "adjuntos": [{"nombre": "FAC-1234.pdf", "contenido_base64": "'"$PDF_B64"'"}]
  }'
# 202: guarda "id". Revisa "omitidos" (no se enviaron; traen "motivo" y a veces "sugerencia")
# y "corregidos" (se enviaron a la dirección corregida). Aquí contador@gamil.com sale en omitidos
# con sugerencia contador@gmail.com.

Campos#

Campo Obligatorio Qué es
negocio sí Clave del negocio que emite (ferreteria-lopez)
tipo sí factura, pedido o notificacion: decide el remitente (facturas@, pedidos@, notificaciones@xr-send.com)
para sí Un correo, varios separados por coma o punto y coma, una lista, o Nombre <correo>
cc no Con copia (visible para todos)
cco no Con copia oculta
asunto sí Hasta 998 caracteres, sin saltos de línea
texto sí Versión en texto plano
html no Versión HTML
responder_a no A dónde llegan las respuestas; si no lo mandas, el correo del negocio
referencia no Tu folio (FAC-1234), hasta 100 caracteres. Sirve para buscar el correo y para detectar reintentos
adjuntos no Lista de {"nombre", "contenido_base64", "tipo_mime"?, "cid"?}
reenvio no true para reenviar a propósito (ver Duplicados)
  • Destinatarios: máximo 10 por correo entre para, cc y cco. Una dirección repetida se envía una sola vez (gana para, luego cc, luego cco). Cada destinatario cuenta 1 en el plan.
  • Remitente: <Negocio> vía Invensys en el plan básico, o solo <Negocio>; las respuestas llegan al responder_a o al correo del negocio.

Adjuntos e imágenes#

  • Cualquier archivo en base64 (PDF, XML, imágenes…). El total de adjuntos no puede pasar el límite del plan (10 MB o 25 MB, según el plan; el contenido decodificado) ni el correo completo 40 MB: si pasa, responde 413.
  • tipo_mime es opcional: se deduce de la extensión.
  • Para mostrar una imagen dentro del HTML (un logo), dale un cid y úsala como <img src="cid:logo">. Las imágenes con cid necesitan html y cada cid debe ser distinto.
  • No se aceptan ejecutables (.exe, .bat, .js, .vbs, .msi…): mándalos en .zip. Responde 422.

La respuesta (202)#

{
  "id": "9c5272e5-85dd-4504-af8b-2747c3229180",
  "estado": "en_cola",
  "destinatarios": 2,
  "omitidos": [],
  "corregidos": [],
  "duplicado": false,
  "aviso": null,
  "uso_dia": {"usados": 130, "limite": 500}
}
  • Guarda el id: con él consultas la entrega y lo reciben tus webhooks como correo_id.
  • destinatarios: cuántos se enviarán (y cuentan para el plan).
  • omitidos y corregidos: ver Direcciones mal escritas y omitidos.
  • uso_dia: lo usado hoy (incluido este correo) y el límite. Si tu plan es por mes, viene además uso_mes (ver Límites del plan).
  • Con la llave de prueba viene además "prueba": true.

Un 202 es éxito: no lo reintentes. Reintenta solo si no hubo respuesta o fue 5xx (ver Errores).

Direcciones mal escritas y omitidos#

Un correo nunca se rechaza entero por una dirección mala si hay otras buenas: la mala se omite, el correo sale a las demás y la omitida viene en omitidos con el motivo. Solo si no queda ningún destinatario responde 422.

Se omiten:

Caso Ejemplo motivo
No es un correo juan@, usuario dirección mal escrita: no es un correo: le falta la @
Dominio con error de captura cliente@gamil.com dirección mal escrita: el dominio «gamil.com» parece un error de captura; ¿quisiste decir cliente@gmail.com? (con sugerencia)
Dirección bloqueada rebotó antes, marcó spam o pidió no recibir lista de supresión: la dirección no existe (rebote permanente)
El dominio no recibe correo cliente@dominio-que-no-existe.mx el dominio no recibe correo (¿está bien escrito?)
{
  "id": "1f0e…",
  "estado": "en_cola",
  "destinatarios": 1,
  "omitidos": [
    {"email": "cliente@gamil.com", "tipo": "para",
     "motivo": "dirección mal escrita: el dominio «gamil.com» parece un error de captura; ¿quisiste decir cliente@gmail.com?",
     "sugerencia": "cliente@gmail.com"}
  ],
  "corregidos": [],
  "duplicado": false,
  "aviso": null,
  "uso_dia": {"usados": 131, "limite": 500}
}

Las omitidas no cuentan para el plan. Qué hacer:

  • Muestra el motivo a quien capturó el correo y pídele que lo corrija en su catálogo de clientes.
  • Si viene sugerencia, confírmala con el cliente antes de usarla: algunos dominios mal escritos los registran terceros para recibir lo que les llega por error.
  • Para validar una dirección al capturarla (antes de enviar), usa GET /v1/supresiones/{email} (ver Direcciones bloqueadas).

Corregidos#

Si Invensys activa la corrección automática para tu negocio, una dirección con el dominio mal escrito se corrige, se envía y viene en corregidos:

"corregidos": [{"original": "cliente@hotmial.com", "enviado_a": "cliente@hotmail.com", "tipo": "para"}]

Corrígela también en tu catálogo.

Cuando no queda nadie (422)#

{"detail": {"mensaje": "Ningún destinatario puede recibir el correo",
            "omitidos": [{"email": "cliente@gmial.com", "tipo": "para",
                          "motivo": "el dominio no recibe correo (¿está bien escrito?)"}]}}

Si todas las direcciones son texto que no es un correo, el 422 viene de la validación (detail es una lista) con el texto «ningún destinatario es un correo válido». No reintentes: corrige la dirección.

En el ejemplo de Enviar un correo se ve cómo leer omitidos y corregidos.

Duplicados#

Si tu sistema manda el mismo correo dos veces en menos de 2 minutos (típico de un reintento automático tras un timeout), el segundo no se envía: responde 202 con el id del original, duplicado: true y un aviso. Así tu cliente no recibe la factura dos veces.

«El mismo correo» es:

  • con referencia: mismo negocio, tipo, referencia, asunto y destinatarios (para, cc, cco). Los adjuntos no se comparan: si al reintentar tu sistema regenera el PDF, sigue siendo el mismo correo;
  • sin referencia: además el mismo texto, html y adjuntos (nombre y contenido).
{
  "id": "9c5272e5-85dd-4504-af8b-2747c3229180",
  "estado": "entregado",
  "destinatarios": 2,
  "omitidos": [],
  "corregidos": [],
  "duplicado": true,
  "aviso": "Es el mismo correo que se aceptó hace menos de 2 min; no se volvió a enviar. Si es un reenvío a propósito, manda \"reenvio\": true.",
  "uso_dia": {"usados": 130, "limite": 500}
}

En un duplicado, estado es el estado actual del original y uso_dia no aumenta.

Reenviar a propósito#

Cuando una persona pide reenviar (por ejemplo, «no me llegó la factura»), manda "reenvio": true: siempre se envía y cuenta para el plan. Es el mismo cuerpo del ejemplo de Enviar un correo con ese campo agregado.

Los correos de prueba solo se comparan con correos de prueba, y los reales con los reales.

Usa siempre referencia con el folio de tu documento: hace la detección de reintentos más confiable y te deja buscar el correo por folio.

Estados de entrega y cómo consultarlos#

Cada destinatario tiene su propio estado, y el correo tiene un estado general.

Estado Qué significa ¿Final?
en_cola Aceptado, a punto de salir no
enviado Salió; esperando la respuesta del servidor del destinatario no
demorado El servidor del destinatario lo está retrasando (buzón lleno, no responde…); se sigue intentando no
entregado El servidor del destinatario lo aceptó sí
rebotado La dirección no existe o la rechazó de forma definitiva: pide otro correo al cliente sí
queja El destinatario lo marcó como spam; ya no se le envía sí
rechazado El servicio de envío lo rechazó (por ejemplo, un adjunto con virus) sí
fallido No se pudo enviar tras varios intentos; viene error sí
parcial Solo el estado general: a unos destinatarios les llegó y a otros no sí

Los estados solo avanzan: un entregado puede pasar a queja, pero nunca vuelve a enviado.

Por id#

GET /v1/correos/{id} (el id de la respuesta del envío):

{
  "id": "9c5272e5-85dd-4504-af8b-2747c3229180",
  "estado": "parcial",
  "tipo": "factura",
  "negocio": "ferreteria-lopez",
  "app": "erp",
  "de": "facturas@xr-send.com",
  "para": "cliente@correo.com",
  "cc": "contador@despacho.mx",
  "cco": null,
  "destinatarios": [
    {"email": "cliente@correo.com", "tipo": "para", "estado": "entregado"},
    {"email": "contador@despacho.mx", "tipo": "cc", "estado": "rebotado"}
  ],
  "asunto": "Tu factura FAC-1234",
  "referencia": "FAC-1234",
  "intentos": 0,
  "error": null,
  "creado": "2026-11-11T16:20:03Z",
  "enviado": "2026-11-11T16:20:05Z",
  "eventos": [
    {"tipo": "Send", "fecha": "2026-11-11T16:20:05Z", "detalle": {}},
    {"tipo": "Delivery", "fecha": "2026-11-11T16:20:07Z", "detalle": {"recipients": ["cliente@correo.com"]}},
    {"tipo": "Bounce", "fecha": "2026-11-11T16:20:08Z", "detalle": {"bounceType": "Permanent"}}
  ]
}

Solo ves correos enviados por tu propio sistema (si no, 404). Con la llave de prueba, solo los de prueba (y viene "prueba": true).

Por folio, destinatario o periodo#

GET /v1/correos?q=FAC-1234 busca por folio (referencia), destinatario, asunto o id. Otros parámetros: periodo (hoy, ayer, 3d, 7d, mes, mes_anterior) o desde/hasta (AAAA-MM-DD, hora del centro de México; sin periodo, los últimos 7 días; máximo 366 días), negocio, estado, orden (reciente, antiguo, estado), limite (1-200, por defecto 50) y saltar para paginar. La respuesta trae correos (cada uno con sus destinatarios) y hay_mas.

ejemplos/curl/estado.sh
#!/bin/sh
# Estado de un correo por id, y búsqueda por folio (referencia).
URL="${XRSEND_URL:-https://api.xr-send.com}"
ID="${1:?uso: estado.sh <id> [referencia]}"
REFERENCIA="${2:-FAC-1234}"

curl -sS "$URL/v1/correos/$ID" -H "X-API-Key: $XRSEND_API_KEY"
echo
# Por folio: busca en asunto, destinatario, folio o id; filtra tú la referencia exacta.
curl -sS -G "$URL/v1/correos" -H "X-API-Key: $XRSEND_API_KEY" \
  --data-urlencode "q=$REFERENCIA" --data-urlencode "periodo=7d"

Sin consultar: webhooks#

En vez de preguntar cada rato, registra un webhook y te avisamos cuando cambie la entrega. Para mostrarle al negocio un resumen, usa también:

  • GET /v1/negocios/{clave}/resumen: totales del periodo, uso de hoy, reputación de 7 días e incidentes.
  • GET /v1/negocios/{clave}/entregas: qué no llegó, por qué y de quién es el problema (Destinatario, Captura del correo, Invensys o En proceso), con la respuesta del servidor del destinatario. Máximo 31 días.

Webhooks#

Un webhook es una dirección de tu sistema a la que avisamos, con un POST, cuando cambia la entrega de un correo. Es opcional: sin webhooks todo funciona igual.

Registrar#

POST /v1/negocios/{clave}/webhooks con la llave de producción (o desde el portal, en Webhooks). La url debe ser https://, pública, en el puerto 443 o uno a partir del 1024; se rechazan las de redes internas. Máximo 5 por negocio.

ejemplos/curl/registrar-webhook.sh
#!/bin/sh
# Registrar un webhook. Es el único ejemplo que usa la llave de PRODUCCIÓN: con la de prueba
# responde 403, para que una llave de prueba filtrada no pueda desviar tus avisos reales.
# Registrar no envía ningún correo.
URL="${XRSEND_URL:-https://api.xr-send.com}"
NEGOCIO="${XRSEND_NEGOCIO:-ferreteria-lopez}"
DESTINO="${XRSEND_WEBHOOK_URL:-https://erp.tu-empresa.mx/webhooks/correo}"   # https, pública

curl -sS -X POST "$URL/v1/negocios/$NEGOCIO/webhooks" \
  -H "X-API-Key: $XRSEND_API_KEY_PRODUCCION" \
  -H "Content-Type: application/json" \
  -d '{"url": "'"$DESTINO"'",
       "eventos": ["entregado", "rebotado", "queja", "no_enviado"],
       "descripcion": "ERP producción"}'
# 201: la respuesta trae "secreto" (whsec_…) UNA sola vez: guárdalo en tu vault.

La respuesta (201) trae el secreto una sola vez (whsec_…): guárdalo en tu vault. Con él verificas la firma de cada aviso.

Eventos#

Evento Cuándo
entregado el servidor del destinatario aceptó el correo
rebotado la dirección no existe o la rechazó de forma definitiva
queja el destinatario lo marcó como spam; ya no se le envía
demorado la entrega se retrasa; se sigue intentando
no_enviado no salió: dirección omitida (mal escrita, bloqueada, dominio con error) o el envío falló
prueba solo con POST …/webhooks/{id}/probar

Cada aviso#

Un POST con Content-Type: application/json, un destinatario por aviso:

{"id": "5b0c2f9e-1d4a-4c39-9a51-0b7a9f0e3c11", "evento": "rebotado",
 "correo_id": "9c5272e5-85dd-4504-af8b-2747c3229180", "referencia": "FAC-1234",
 "negocio": "ferreteria-lopez", "destinatario": "cliente@correo.com",
 "fecha": "2026-11-19T17:02:11Z",
 "causa": "La dirección no existe o el servidor del destinatario la rechazó de forma definitiva. Hay que pedir al cliente un correo correcto. Respuesta: 550 5.1.1 user unknown",
 "estado": "rebotado", "sugerencia": "cliente@gmail.com"}

correo_id es el de POST /v1/correos (null si la petición entera se rechazó); sugerencia solo viene si el dominio parece mal escrito. En los avisos de correos de prueba viene además "prueba": true. Ignora los campos que no conozcas: se pueden agregar más.

Encabezados:

Encabezado Valor
X-XRSend-Evento el evento
X-XRSend-Id id del aviso; el mismo en cada reintento: si ya lo procesaste, ignóralo
X-XRSend-Fecha momento del envío, en segundos desde 1970 (epoch)
X-XRSend-Firma sha256=<hex>
X-XRSend-Prueba 1, solo en avisos de correos de prueba

Verificar la firma#

La firma es el HMAC-SHA256 con tu secreto (el texto completo, con whsec_, como clave) sobre "{X-XRSend-Fecha}.{cuerpo}": la fecha, un punto y el cuerpo tal como llegó (los bytes, antes de convertirlo a JSON), en hexadecimal en minúsculas y con el prefijo sha256=.

  1. Lee el cuerpo crudo (no lo vuelvas a serializar: un espacio distinto cambia la firma).
  2. Rechaza si X-XRSend-Fecha está a más de 5 minutos de tu reloj (evita que repitan un aviso viejo).
  3. Calcula "sha256=" + hex(HMAC_SHA256(secreto, fecha + "." + cuerpo)).
  4. Compárala con X-XRSend-Firma en tiempo constante. Si no coincide, responde 401 y no proceses.
  5. Responde 2xx rápido (en menos de 10 s) y procesa después; usa X-XRSend-Id para no procesar dos veces.

Vector de prueba: secreto whsec_prueba, fecha 1700000000, cuerpo {"evento":"prueba"} → sha256=66a878212ff983a02a3a40c45a2575a9fdf75a96ac7dc96e94c07a10ec53206c.

ejemplos/curl/webhook.sh
#!/bin/sh
# Verificar la firma de un aviso con openssl (útil para depurar; en producción usa tu lenguaje).
# Guarda el cuerpo TAL COMO LLEGÓ en cuerpo.json y pasa los encabezados:
#   XRSEND_WEBHOOK_SECRETO=whsec_... ./webhook.sh cuerpo.json "$X_XRSEND_FECHA" "$X_XRSEND_FIRMA"
CUERPO="${1:?cuerpo.json}"; FECHA="${2:?X-XRSend-Fecha}"; FIRMA="${3:?X-XRSend-Firma}"

ahora=$(date +%s)
dif=$((ahora - FECHA)); [ $dif -lt 0 ] && dif=$((-dif))
if [ $dif -gt 300 ]; then echo "Rechazado: fecha de hace más de 5 minutos"; exit 1; fi

esperada="sha256=$( { printf '%s.' "$FECHA"; cat "$CUERPO"; } \
  | openssl dgst -sha256 -hmac "$XRSEND_WEBHOOK_SECRETO" | sed 's/^.* //')"
if [ "$esperada" = "$FIRMA" ]; then echo "Firma válida"; else echo "Firma inválida"; exit 1; fi

Reintentos y pausa#

Cualquier respuesta que no sea 2xx, un error de red, más de 10 s o una redirección (no se siguen) cuentan como falla. Se reintenta con espera creciente (30 s, 1, 2, 4, 8, 16, 32 min y luego cada hora) durante 24 horas; después el aviso queda fallido. Tras 20 fallas seguidas el webhook se pausa y avisamos al correo del negocio; reactívalo cuando tu sistema ya responda (las fallas de avisos de prueba no cuentan para la pausa).

Para probar tu receptor: POST /v1/negocios/{clave}/webhooks/{id}/probar manda un aviso prueba ahora mismo y responde lo que contestó tu servidor; o envía correos con la llave de prueba a las direcciones de prueba.xr-send.com. Historial: GET …/webhooks/{id}/envios; reenviar uno: POST …/envios/{envio_id}/reenviar; rotar el secreto: POST …/webhooks/{id}/rotar-secreto (el anterior deja de valer en ese momento).

Errores y qué hacer#

Los errores traen el motivo en detail: un texto, un objeto con más datos, o (en el 422 de validación) la lista de campos inválidos. Regla general: reintenta solo los 5xx, los errores de red y el 429; un 4xx volverá a fallar igual.

Código Cuándo detail (ejemplo) Qué hacer
202 Aceptado (o duplicado) — Guardar el id. No reintentar
401 Falta la llave, es inválida o la app está desactivada "API key inválida o app desactivada" / "Falta el header X-API-Key" Revisar la llave. No reintentar
403 Negocio suspendido o plan desactivado {"mensaje": "El negocio 'ferreteria-lopez' está suspendido", "motivo": "…"} No reintentar: avisar al negocio y a Invensys
404 El negocio no existe o no está habilitado para tu sistema; o el correo no es tuyo "El negocio 'x' no existe o no está habilitado para la app 'erp'" Revisar la clave del negocio
409 Webhooks: ya hay uno con esa URL o se llegó al máximo "Ya hay un webhook con esa dirección." No reintentar
413 Adjuntos más grandes que el plan, o el correo pasa de 40 MB "Los adjuntos superan 10 MB (límite del plan)" Reducir o mandar un enlace
422 Datos inválidos (sin para, más de 10 destinatarios, adjunto ejecutable, cid sin html, base64 inválido) o ningún destinatario puede recibir lista de campos, o {"mensaje": "Ningún destinatario puede recibir el correo", "omitidos": […]} Corregir el dato. Nunca reintentar
429 El correo no cabe en lo que le queda al plan (hoy o este mes) {"mensaje": "Límite diario del plan alcanzado; se reinicia a medianoche (hora de México)", "plan": "basico", "limite": 500, "usados": 499, "requeridos": 2} Esperar al reinicio (medianoche o el día 1) o pedir más plan; reintentar más tarde
5xx / sin respuesta Falla nuestra o de red — Reintentar con espera creciente. Si se aceptó antes del corte, el reintento sale como duplicado y no se envía dos veces

Con la llave de prueba hay además un 429 propio del modo de prueba ({"mensaje": "Modo de prueba: máximo 1000 correos de prueba por hora por app…", "prueba": true, "reintentar_en_s": 120}) y un 403 si intentas registrar, cambiar o borrar webhooks.

Reintentos con espera#

Un buen cliente: reintenta 429, 5xx y errores de red con espera creciente (por ejemplo 1, 2, 4, 8 s, con un tope y un poco de azar); nunca reintenta 4xx distintos de 429; y gracias a la detección de duplicados, un reintento tras un timeout no duplica el correo.

ejemplos/curl/errores.sh
#!/bin/sh
# Enviar con reintentos: solo 429, 5xx o sin respuesta. Un 4xx (401, 403, 404, 413, 422) no se reintenta.
URL="${XRSEND_URL:-https://api.xr-send.com}"
NEGOCIO="${XRSEND_NEGOCIO:-ferreteria-lopez}"
CUERPO='{"negocio": "'"$NEGOCIO"'", "tipo": "factura", "para": "bloqueado@prueba.xr-send.com",
         "asunto": "Tu factura FAC-1235", "texto": "Hola", "referencia": "FAC-1235"}'

R=$(mktemp)
espera=1
for intento in 1 2 3 4 5; do
  codigo=$(curl -sS -o "$R" -w '%{http_code}' -X POST "$URL/v1/correos" \
    -H "X-API-Key: $XRSEND_API_KEY" -H "Content-Type: application/json" -d "$CUERPO") || codigo=000
  case "$codigo" in
    202) echo "Aceptado:"; cat "$R"; exit 0 ;;
    429|5*|000)
      echo "HTTP $codigo, reintento en $espera s"; cat "$R" 2>/dev/null; echo
      sleep $((espera + $(od -An -N1 -tu1 /dev/urandom) % 2)); espera=$((espera * 2)) ;;
    *) echo "HTTP $codigo: no se reintenta, corrige el dato:"; cat "$R"; echo; exit 1 ;;
  esac
done
echo "Sin éxito tras 5 intentos"; exit 1
# Este ejemplo responde 422 {"detail": {"mensaje": "Ningún destinatario puede recibir el correo", "omitidos": […]}}

Límites del plan, uso diario y mensual#

Cada negocio tiene un plan que limita cuántos destinatarios puede enviar por día o por mes: cada dirección en para, cc y cco cuenta 1. Las omitidas, los duplicados, los correos fallido o rechazado y los de prueba no cuentan.

  • Plan por día: se reinicia a medianoche, hora del centro de México.
  • Plan por mes: se reinicia el día 1 a las 00:00, hora del centro de México. Las respuestas traen además uso_mes.

Si un correo no cabe en lo que queda, responde 429 con limite, usados y requeridos (ver Errores) y no se envía nada; un correo nunca se envía a medias por el límite.

Consultar el uso#

  • GET /v1/negocios/{clave}/uso: el plan, si el negocio está activo y el uso de hoy (uso_dia con usados, limite, restantes; en planes por mes, también uso_mes).
  • GET /v1/negocios/{clave}/uso-mensual?mes=AAAA-MM: correos y destinatarios del mes, por día y por estado. Úsalo para mostrarle al negocio su consumo.
ejemplos/curl/uso.sh
#!/bin/sh
# Uso del plan: hoy (y el mes, si el plan es mensual) y el consumo del mes por día.
URL="${XRSEND_URL:-https://api.xr-send.com}"
NEGOCIO="${XRSEND_NEGOCIO:-ferreteria-lopez}"

curl -sS "$URL/v1/negocios/$NEGOCIO/uso" -H "X-API-Key: $XRSEND_API_KEY"
echo
curl -sS "$URL/v1/negocios/$NEGOCIO/uso-mensual?mes=$(date +%Y-%m)" -H "X-API-Key: $XRSEND_API_KEY"
{"clave": "ferreteria-lopez", "nombre": "Ferretería López", "activo": true,
 "motivo_suspension": null, "plan": "basico",
 "uso_dia": {"usados": 128, "limite": 500, "restantes": 372}}

En un plan por mes, al final viene "uso_mes": {"usados": 1840, "limite": 10000, "restantes": 8160} y uso_dia.limite es lo que se puede llevar hoy (lo enviado hoy más lo que queda del mes).

Arranque gradual#

Los negocios nuevos empiezan con un tope diario de 200 destinatarios aunque su plan sea mayor. Cada semana, si el negocio envió al menos 100 y sus rebotes y quejas fueron bajos, el tope se duplica, hasta llegar a su plan. Mientras tanto, el 429 lo dice («Límite diario del periodo de arranque alcanzado…»). Así cuidamos la reputación de envío que comparten todos los negocios.

Reputación#

Si en 7 días un negocio pasa de 6 % de rebotes o 0.3 % de quejas (con al menos 50 destinatarios), su envío se suspende y la API responde 403 con el motivo; antes de llegar ahí avisamos al correo del negocio. La forma de evitarlo: corregir las direcciones que rebotan (ver Direcciones bloqueadas) y enviar solo correos transaccionales que el cliente espera.

Direcciones bloqueadas#

Una dirección se bloquea (lista de supresión) cuando:

  • rebotó de forma permanente (no existe),
  • el destinatario marcó un correo como spam,
  • la persona pidió no recibir más correos, o Invensys la bloqueó.

El bloqueo es para todos los negocios del servicio: una dirección que no existe no existe para nadie, y los rebotes y quejas dañan la reputación de envío que todos comparten. Un correo a una dirección bloqueada no falla: esa dirección se omite y sale en omitidos.

¿Se le puede enviar a esta dirección?#

GET /v1/supresiones/{email} responde si es enviable, para pedirle al cliente otra dirección al capturarla. No hace falta llamarlo antes de cada envío.

ejemplos/curl/direccion.sh
#!/bin/sh
# ¿Se le puede enviar a esta dirección? (al capturarla en tu sistema)
URL="${XRSEND_URL:-https://api.xr-send.com}"
NEGOCIO="${XRSEND_NEGOCIO:-ferreteria-lopez}"
EMAIL="${1:-cliente@gamil.com}"     # el + se codifica como %2B

curl -sS "$URL/v1/supresiones/$(printf %s "$EMAIL" | sed 's/+/%2B/g')" -H "X-API-Key: $XRSEND_API_KEY"
echo
# Direcciones bloqueadas de los clientes del negocio
curl -sS "$URL/v1/negocios/$NEGOCIO/supresiones?limite=50" -H "X-API-Key: $XRSEND_API_KEY"
{"email": "cliente@correo.com", "enviable": false,
 "motivo": "lista de supresión: la dirección no existe (rebote permanente)",
 "desde": "2026-11-12T18:03:11Z", "sugerencia": null}

También avisa de direcciones mal escritas y dominios que no reciben correo, con sugerencia si el dominio parece un error de captura.

Las de los clientes de un negocio#

GET /v1/negocios/{clave}/supresiones lista las direcciones bloqueadas de los clientes del negocio (parámetros q, motivo, limite, saltar). por_tus_envios dice si el bloqueo salió de un correo de este negocio; en ese caso vienen respuesta_servidor y correo_id. Úsalo para pedirle al negocio que corrija esos correos en su catálogo.

Desbloquear una dirección (por ejemplo, el cliente ya la arregló) lo hace Invensys: escribe a contacto@invensys.mx. Con la llave de prueba, un rebote o una queja simulados no bloquean nada.

Dominio propio#

Por defecto los correos salen de facturas@, pedidos@ o notificaciones@xr-send.com, con el nombre del negocio. Un negocio puede enviar desde su propio dominio (por ejemplo facturas@cliente.com) para que su marca se vea completa.

Cómo se hace (lo activa Invensys; pídelo a contacto@invensys.mx):

  1. Nos dices el dominio o subdominio (te recomendamos un subdominio, como facturas.cliente.com).
  2. Te damos los registros DNS a publicar en el DNS del dominio: - un CNAME <selector>._domainkey.<tu dominio> que apunta a un nombre nuestro, con el que los correos salen firmados (DKIM) a nombre de tu dominio; - si tu dominio no tiene DMARC, te sugerimos un TXT _dmarc.<tu dominio> con v=DMARC1; p=none; adkim=r; aspf=r (Gmail y Yahoo lo piden; súbelo a quarantine cuando todo esté bien).
  3. Verificamos que el DNS esté bien publicado y lo activamos para el negocio.

Tu integración no cambia: mismos campos y mismas respuestas; solo cambia el remitente. El campo de de GET /v1/correos/{id} muestra la dirección desde la que salió.

Usar con asistentes de IA (MCP)#

La API también se puede usar desde asistentes de IA compatibles con MCP (Model Context Protocol), como Claude Code, para preguntar por la integración, revisar el estado de tus correos o probar envíos mientras desarrollas.

  • Dirección: https://api.xr-send.com/mcp (transporte Streamable HTTP).
  • Llave: la misma de la API, como Authorization: Bearer <llave>. Ve exactamente lo mismo que esa llave en la API: los negocios de tu sistema y nada más.
  • Recomendado: usa la llave de prueba (xrs_test_…). Así el asistente no puede enviar correos de verdad.

Agregarlo en Claude Code#

claude mcp add --transport http correo-invensys https://api.xr-send.com/mcp \
  --header "Authorization: Bearer xrs_test_..."

Otros clientes MCP#

La mayoría acepta una configuración JSON como esta:

{
  "mcpServers": {
    "correo-invensys": {
      "type": "http",
      "url": "https://api.xr-send.com/mcp",
      "headers": {"Authorization": "Bearer xrs_test_..."}
    }
  }
}

No pongas la llave en archivos que se suban a tu repositorio.

Herramientas#

Herramienta Qué hace
buscar_en_guia Busca en esta guía; con lenguaje (curl, python, php, csharp, java, node) trae los ejemplos en ese lenguaje
enviar_correo Envía un correo. Con la llave de prueba, simulado. Con la de producción se envía de verdad y exige confirmar_envio_real: true
estado_correo Estado de un correo por id o por referencia
buscar_correos Busca correos por periodo, estado, destinatario, asunto o folio
direcciones_bloqueadas Direcciones bloqueadas de los clientes de un negocio (solo lectura)
consultar_direccion Si se le puede enviar a una dirección
uso_del_plan Uso de hoy y del mes de un negocio
probar_webhook Manda el aviso de prueba a un webhook del negocio
verificar_firma_webhook Verifica la firma de un aviso que recibiste (cuerpo, encabezados y secreto); el secreto no se guarda

Las secciones de esta guía también están disponibles como recursos (guia://…).

Las mismas reglas de la API aplican: el asistente no puede ver datos de otros negocios ni desbloquear direcciones. Hay un tope de peticiones por minuto por llave (429 si se pasa).