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.
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.
- 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. - Guárdala en una variable de entorno, nunca en el código:
bash
export XRSEND_API_KEY="xrs_test_..."
- Ten a la mano la clave de tu negocio (por ejemplo
ferreteria-lopez): te la damos al darlo de alta y va en el camponegociode cada correo. - Envía un correo a
entregado@prueba.xr-send.com:
#!/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}
# Primer correo con la llave de PRUEBA (xrs_test_…): nada se envía de verdad.
# pip install requests ; export XRSEND_API_KEY="xrs_test_..."
import os
import requests
URL = os.environ.get("XRSEND_URL", "https://api.xr-send.com")
r = requests.post(f"{URL}/v1/correos", timeout=30,
headers={"X-API-Key": os.environ["XRSEND_API_KEY"]},
json={"negocio": os.environ.get("XRSEND_NEGOCIO", "ferreteria-lopez"),
"tipo": "notificacion",
"para": "entregado@prueba.xr-send.com",
"asunto": "Mi primer correo",
"texto": "Hola, esto es una prueba."})
r.raise_for_status()
datos = r.json()
print("id:", datos["id"], "| estado:", datos["estado"], "| prueba:", datos.get("prueba", False))
<?php
// Primer correo con la llave de PRUEBA (xrs_test_…): nada se envía de verdad.
// export XRSEND_API_KEY="xrs_test_..." ; php primer_correo.php (extensión curl)
$url = getenv('XRSEND_URL') ?: 'https://api.xr-send.com';
$ch = curl_init("$url/v1/correos");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('XRSEND_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'negocio' => getenv('XRSEND_NEGOCIO') ?: 'ferreteria-lopez',
'tipo' => 'notificacion',
'para' => 'entregado@prueba.xr-send.com',
'asunto' => 'Mi primer correo',
'texto' => 'Hola, esto es una prueba.',
]),
]);
$datos = json_decode(curl_exec($ch), true);
$codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($codigo !== 202) {
exit("HTTP $codigo: " . json_encode($datos['detail'] ?? null, JSON_UNESCAPED_UNICODE) . "\n");
}
echo "id: {$datos['id']} | estado: {$datos['estado']} | prueba: " . (($datos['prueba'] ?? false) ? 'sí' : 'no') . "\n";
// Primer correo con la llave de PRUEBA (xrs_test_…): nada se envía de verdad.
// .NET 8, proyecto de consola (dotnet new console) con este archivo como Program.cs.
// export XRSEND_API_KEY="xrs_test_..." ; dotnet run
using System.Net.Http.Json;
using System.Text.Json;
var url = Environment.GetEnvironmentVariable("XRSEND_URL") ?? "https://api.xr-send.com";
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("XRSEND_API_KEY"));
var r = await http.PostAsJsonAsync($"{url}/v1/correos", new
{
negocio = Environment.GetEnvironmentVariable("XRSEND_NEGOCIO") ?? "ferreteria-lopez",
tipo = "notificacion",
para = "entregado@prueba.xr-send.com",
asunto = "Mi primer correo",
texto = "Hola, esto es una prueba.",
});
var datos = await r.Content.ReadFromJsonAsync<JsonElement>();
if ((int)r.StatusCode != 202) throw new Exception($"HTTP {(int)r.StatusCode}: {datos.GetProperty("detail")}");
var prueba = datos.TryGetProperty("prueba", out var p) && p.GetBoolean();
Console.WriteLine($"id: {datos.GetProperty("id")} | estado: {datos.GetProperty("estado")} | prueba: {prueba}");
// Primer correo con la llave de PRUEBA (xrs_test_…): nada se envía de verdad.
// Java 17+ (java.net.http) y Jackson para el JSON: com.fasterxml.jackson.core:jackson-databind:2.17.2
// export XRSEND_API_KEY="xrs_test_..." ; java -cp "jackson/*" PrimerCorreo.java
// HTTP/1.1 explícito: así no intenta pasar a HTTP/2 sin TLS (h2c), que algunos proxies rechazan.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;
public class PrimerCorreo {
public static void main(String[] args) throws Exception {
String url = System.getenv().getOrDefault("XRSEND_URL", "https://api.xr-send.com");
ObjectMapper json = new ObjectMapper();
String cuerpo = json.writeValueAsString(Map.of(
"negocio", System.getenv().getOrDefault("XRSEND_NEGOCIO", "ferreteria-lopez"),
"tipo", "notificacion",
"para", "entregado@prueba.xr-send.com",
"asunto", "Mi primer correo",
"texto", "Hola, esto es una prueba."));
HttpRequest pet = HttpRequest.newBuilder(URI.create(url + "/v1/correos"))
.timeout(Duration.ofSeconds(30))
.header("X-API-Key", System.getenv("XRSEND_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(cuerpo)).build();
HttpResponse<String> r = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build().send(pet, HttpResponse.BodyHandlers.ofString());
JsonNode datos = json.readTree(r.body());
if (r.statusCode() != 202) throw new RuntimeException("HTTP " + r.statusCode() + ": " + datos.get("detail"));
System.out.println("id: " + datos.get("id").asText() + " | estado: " + datos.get("estado").asText()
+ " | prueba: " + datos.path("prueba").asBoolean(false));
}
}
// Primer correo con la llave de PRUEBA (xrs_test_…): nada se envía de verdad.
// Node 18+ (fetch incluido). export XRSEND_API_KEY="xrs_test_..." ; node primer-correo.mjs
const URL_API = process.env.XRSEND_URL ?? "https://api.xr-send.com";
const r = await fetch(`${URL_API}/v1/correos`, {
method: "POST",
headers: { "X-API-Key": process.env.XRSEND_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
negocio: process.env.XRSEND_NEGOCIO ?? "ferreteria-lopez",
tipo: "notificacion",
para: "entregado@prueba.xr-send.com",
asunto: "Mi primer correo",
texto: "Hola, esto es una prueba.",
}),
});
const datos = await r.json();
if (r.status !== 202) throw new Error(`HTTP ${r.status}: ${JSON.stringify(datos.detail)}`);
console.log(`id: ${datos.id} | estado: ${datos.estado} | prueba: ${datos.prueba ?? false}`);
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/correosyGET /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": truesi 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.
#!/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.
# Enviar una factura con PDF adjunto, copia y folio (referencia), y revisar omitidos/corregidos.
# pip install requests ; export XRSEND_API_KEY="xrs_test_..."
import base64
import os
import requests
URL = os.environ.get("XRSEND_URL", "https://api.xr-send.com")
pdf = b"%PDF-1.4\n% factura de ejemplo\n" # en tu sistema: open("FAC-1234.pdf", "rb").read()
correo = {
"negocio": os.environ.get("XRSEND_NEGOCIO", "ferreteria-lopez"),
"tipo": "factura",
"para": "Cliente Ejemplo <entregado@prueba.xr-send.com>",
"cc": ["contador@gamil.com"], # dominio mal escrito: sale en omitidos
"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": base64.b64encode(pdf).decode()}],
# "reenvio": True, # solo si una persona pide reenviar el mismo correo a propósito
}
r = requests.post(f"{URL}/v1/correos", json=correo, timeout=30,
headers={"X-API-Key": os.environ["XRSEND_API_KEY"]})
if r.status_code != 202:
raise SystemExit(f"HTTP {r.status_code}: {r.json().get('detail')}")
datos = r.json()
print("id:", datos["id"], "| destinatarios:", datos["destinatarios"], "| duplicado:", datos["duplicado"])
for o in datos["omitidos"]:
# No se envió a esta dirección: muéstralo a quien capturó el correo.
print(f" omitido {o['email']} ({o['tipo']}): {o['motivo']}")
if o.get("sugerencia"):
print(f" ¿quisiste decir {o['sugerencia']}? Confírmalo con el cliente.")
for c in datos.get("corregidos", []):
print(f" corregido {c['original']} -> {c['enviado_a']}: corrígelo también en tu catálogo")
<?php
// Enviar una factura con PDF adjunto, copia y folio (referencia), y revisar omitidos/corregidos.
// export XRSEND_API_KEY="xrs_test_..." ; php enviar.php (extensión curl)
$url = getenv('XRSEND_URL') ?: 'https://api.xr-send.com';
$pdf = "%PDF-1.4\n% factura de ejemplo\n"; // en tu sistema: file_get_contents('FAC-1234.pdf')
$correo = [
'negocio' => getenv('XRSEND_NEGOCIO') ?: 'ferreteria-lopez',
'tipo' => 'factura',
'para' => 'Cliente Ejemplo <entregado@prueba.xr-send.com>',
'cc' => ['contador@gamil.com'], // dominio mal escrito: sale en omitidos
'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' => base64_encode($pdf)]],
// 'reenvio' => true, // solo si una persona pide reenviar el mismo correo a propósito
];
$ch = curl_init("$url/v1/correos");
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('XRSEND_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($correo),
]);
$datos = json_decode(curl_exec($ch), true);
$codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($codigo !== 202) {
exit("HTTP $codigo: " . json_encode($datos['detail'] ?? null, JSON_UNESCAPED_UNICODE) . "\n");
}
echo "id: {$datos['id']} | destinatarios: {$datos['destinatarios']}\n";
foreach ($datos['omitidos'] as $o) {
// No se envió a esta dirección: muéstralo a quien capturó el correo.
echo " omitido {$o['email']} ({$o['tipo']}): {$o['motivo']}\n";
if (!empty($o['sugerencia'])) {
echo " ¿quisiste decir {$o['sugerencia']}? Confírmalo con el cliente.\n";
}
}
foreach ($datos['corregidos'] ?? [] as $c) {
echo " corregido {$c['original']} -> {$c['enviado_a']}: corrígelo también en tu catálogo\n";
}
// Enviar una factura con PDF adjunto, copia y folio (referencia), y revisar omitidos/corregidos.
// .NET 8, proyecto de consola con este archivo como Program.cs.
// export XRSEND_API_KEY="xrs_test_..." ; dotnet run
using System.Net.Http.Json;
using System.Text;
using System.Text.Json;
var url = Environment.GetEnvironmentVariable("XRSEND_URL") ?? "https://api.xr-send.com";
var pdf = Encoding.ASCII.GetBytes("%PDF-1.4\n% factura de ejemplo\n"); // en tu sistema: File.ReadAllBytes("FAC-1234.pdf")
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("XRSEND_API_KEY"));
var correo = new Dictionary<string, object>
{
["negocio"] = Environment.GetEnvironmentVariable("XRSEND_NEGOCIO") ?? "ferreteria-lopez",
["tipo"] = "factura",
["para"] = "Cliente Ejemplo <entregado@prueba.xr-send.com>",
["cc"] = new[] { "contador@gamil.com" }, // dominio mal escrito: sale en omitidos
["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"] = new[] { new { nombre = "FAC-1234.pdf", contenido_base64 = Convert.ToBase64String(pdf) } },
// ["reenvio"] = true, // solo si una persona pide reenviar el mismo correo a propósito
};
var r = await http.PostAsJsonAsync($"{url}/v1/correos", correo);
var datos = await r.Content.ReadFromJsonAsync<JsonElement>();
if ((int)r.StatusCode != 202) throw new Exception($"HTTP {(int)r.StatusCode}: {datos.GetProperty("detail")}");
Console.WriteLine($"id: {datos.GetProperty("id")} | destinatarios: {datos.GetProperty("destinatarios")}");
foreach (var o in datos.GetProperty("omitidos").EnumerateArray())
{
// No se envió a esta dirección: muéstralo a quien capturó el correo.
Console.WriteLine($" omitido {o.GetProperty("email")} ({o.GetProperty("tipo")}): {o.GetProperty("motivo")}");
if (o.TryGetProperty("sugerencia", out var s) && s.ValueKind == JsonValueKind.String)
Console.WriteLine($" ¿quisiste decir {s}? Confírmalo con el cliente.");
}
if (datos.TryGetProperty("corregidos", out var corregidos))
foreach (var c in corregidos.EnumerateArray())
Console.WriteLine($" corregido {c.GetProperty("original")} -> {c.GetProperty("enviado_a")}: corrígelo también en tu catálogo");
// Enviar una factura con PDF adjunto, copia y folio (referencia), y revisar omitidos/corregidos.
// Java 17+ y Jackson (com.fasterxml.jackson.core:jackson-databind:2.17.2).
// export XRSEND_API_KEY="xrs_test_..." ; java -cp "jackson/*" Enviar.java
// HTTP/1.1 explícito: así no intenta pasar a HTTP/2 sin TLS (h2c), que algunos proxies rechazan.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.Base64;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
public class Enviar {
public static void main(String[] args) throws Exception {
String url = System.getenv().getOrDefault("XRSEND_URL", "https://api.xr-send.com");
byte[] pdf = "%PDF-1.4\n% factura de ejemplo\n".getBytes(StandardCharsets.US_ASCII); // o Files.readAllBytes(...)
Map<String, Object> correo = new LinkedHashMap<>();
correo.put("negocio", System.getenv().getOrDefault("XRSEND_NEGOCIO", "ferreteria-lopez"));
correo.put("tipo", "factura");
correo.put("para", "Cliente Ejemplo <entregado@prueba.xr-send.com>");
correo.put("cc", List.of("contador@gamil.com")); // dominio mal escrito: sale en omitidos
correo.put("asunto", "Tu factura FAC-1234");
correo.put("texto", "Adjuntamos tu factura FAC-1234.");
correo.put("html", "<p>Adjuntamos tu factura <b>FAC-1234</b>.</p>");
correo.put("referencia", "FAC-1234");
correo.put("adjuntos", List.of(Map.of("nombre", "FAC-1234.pdf",
"contenido_base64", Base64.getEncoder().encodeToString(pdf))));
// correo.put("reenvio", true); // solo si una persona pide reenviar el mismo correo a propósito
ObjectMapper json = new ObjectMapper();
HttpRequest pet = HttpRequest.newBuilder(URI.create(url + "/v1/correos"))
.timeout(Duration.ofSeconds(30))
.header("X-API-Key", System.getenv("XRSEND_API_KEY"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json.writeValueAsString(correo))).build();
HttpResponse<String> r = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build().send(pet, HttpResponse.BodyHandlers.ofString());
JsonNode datos = json.readTree(r.body());
if (r.statusCode() != 202) throw new RuntimeException("HTTP " + r.statusCode() + ": " + datos.get("detail"));
System.out.println("id: " + datos.get("id").asText() + " | destinatarios: " + datos.get("destinatarios").asInt());
for (JsonNode o : datos.get("omitidos")) {
// No se envió a esta dirección: muéstralo a quien capturó el correo.
System.out.println(" omitido " + o.get("email").asText() + " (" + o.get("tipo").asText() + "): " + o.get("motivo").asText());
if (o.hasNonNull("sugerencia"))
System.out.println(" ¿quisiste decir " + o.get("sugerencia").asText() + "? Confírmalo con el cliente.");
}
for (JsonNode c : datos.path("corregidos"))
System.out.println(" corregido " + c.get("original").asText() + " -> " + c.get("enviado_a").asText()
+ ": corrígelo también en tu catálogo");
}
}
// Enviar una factura con PDF adjunto, copia y folio (referencia), y revisar omitidos/corregidos.
// Node 18+. export XRSEND_API_KEY="xrs_test_..." ; node enviar.mjs
const URL_API = process.env.XRSEND_URL ?? "https://api.xr-send.com";
const pdf = Buffer.from("%PDF-1.4\n% factura de ejemplo\n"); // en tu sistema: fs.readFileSync("FAC-1234.pdf")
const correo = {
negocio: process.env.XRSEND_NEGOCIO ?? "ferreteria-lopez",
tipo: "factura",
para: "Cliente Ejemplo <entregado@prueba.xr-send.com>",
cc: ["contador@gamil.com"], // dominio mal escrito: sale en omitidos
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.toString("base64") }],
// reenvio: true, // solo si una persona pide reenviar el mismo correo a propósito
};
const r = await fetch(`${URL_API}/v1/correos`, {
method: "POST",
headers: { "X-API-Key": process.env.XRSEND_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify(correo),
});
const datos = await r.json();
if (r.status !== 202) throw new Error(`HTTP ${r.status}: ${JSON.stringify(datos.detail)}`);
console.log(`id: ${datos.id} | destinatarios: ${datos.destinatarios} | duplicado: ${datos.duplicado}`);
for (const o of datos.omitidos) {
// No se envió a esta dirección: muéstralo a quien capturó el correo.
console.log(` omitido ${o.email} (${o.tipo}): ${o.motivo}`);
if (o.sugerencia) console.log(` ¿quisiste decir ${o.sugerencia}? Confírmalo con el cliente.`);
}
for (const c of datos.corregidos ?? []) {
console.log(` corregido ${c.original} -> ${c.enviado_a}: corrígelo también en tu catálogo`);
}
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,ccycco. Una dirección repetida se envía una sola vez (ganapara, luegocc, luegocco). Cada destinatario cuenta 1 en el plan. - Remitente:
<Negocio> vía Invensysen el plan básico, o solo<Negocio>; las respuestas llegan alresponder_ao 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_mimees opcional: se deduce de la extensión.- Para mostrar una imagen dentro del HTML (un logo), dale un
cidy úsala como<img src="cid:logo">. Las imágenes concidnecesitanhtmly cadaciddebe 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 comocorreo_id. destinatarios: cuántos se enviarán (y cuentan para el plan).omitidosycorregidos: 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ásuso_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
motivoa 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,asuntoy 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 mismotexto,htmly 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.
#!/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"
# Estado de un correo por id y búsqueda por folio (referencia).
# pip install requests ; export XRSEND_API_KEY="xrs_test_..."
import os
import sys
import requests
URL = os.environ.get("XRSEND_URL", "https://api.xr-send.com")
H = {"X-API-Key": os.environ["XRSEND_API_KEY"]}
def por_id(correo_id: str) -> dict:
r = requests.get(f"{URL}/v1/correos/{correo_id}", headers=H, timeout=30)
if r.status_code == 404:
raise SystemExit("No existe o no lo envió tu sistema")
r.raise_for_status()
return r.json()
def por_referencia(referencia: str) -> list[dict]:
# q busca en folio, destinatario, asunto e id: se filtra la referencia exacta.
r = requests.get(f"{URL}/v1/correos", headers=H, timeout=30, params={"q": referencia, "periodo": "7d"})
r.raise_for_status()
return [c for c in r.json()["correos"] if c["referencia"] == referencia]
referencia = sys.argv[1] if len(sys.argv) > 1 else "FAC-1234"
for resumen in por_referencia(referencia):
c = por_id(resumen["id"])
print(f"{c['id']} {c['referencia']} → {c['estado']}")
for d in c["destinatarios"]:
print(f" {d['tipo']:4} {d['email']}: {d['estado']}")
<?php
// Estado de un correo por id y búsqueda por folio (referencia).
// export XRSEND_API_KEY="xrs_test_..." ; php estado.php FAC-1234 (extensión curl)
$url = getenv('XRSEND_URL') ?: 'https://api.xr-send.com';
function pedir(string $direccion): array {
$ch = curl_init($direccion);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('XRSEND_API_KEY')]]);
$datos = json_decode(curl_exec($ch), true);
$codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($codigo !== 200) {
throw new RuntimeException("HTTP $codigo: " . json_encode($datos['detail'] ?? null, JSON_UNESCAPED_UNICODE));
}
return $datos;
}
$referencia = $argv[1] ?? 'FAC-1234';
// q busca en folio, destinatario, asunto e id: se filtra la referencia exacta.
$lista = pedir("$url/v1/correos?" . http_build_query(['q' => $referencia, 'periodo' => '7d']));
foreach ($lista['correos'] as $resumen) {
if ($resumen['referencia'] !== $referencia) continue;
$c = pedir("$url/v1/correos/" . rawurlencode($resumen['id']));
echo "{$c['id']} {$c['referencia']} → {$c['estado']}\n";
foreach ($c['destinatarios'] as $d) {
echo " {$d['tipo']} {$d['email']}: {$d['estado']}\n";
}
}
// Estado de un correo por id y búsqueda por folio (referencia).
// .NET 8, proyecto de consola con este archivo como Program.cs.
// export XRSEND_API_KEY="xrs_test_..." ; dotnet run -- FAC-1234
using System.Net.Http.Json;
using System.Text.Json;
var url = Environment.GetEnvironmentVariable("XRSEND_URL") ?? "https://api.xr-send.com";
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("XRSEND_API_KEY"));
async Task<JsonElement> Pedir(string ruta)
{
var r = await http.GetAsync($"{url}{ruta}");
var datos = await r.Content.ReadFromJsonAsync<JsonElement>();
if ((int)r.StatusCode != 200) throw new Exception($"HTTP {(int)r.StatusCode}: {datos.GetProperty("detail")}");
return datos;
}
var referencia = args.Length > 0 ? args[0] : "FAC-1234";
// q busca en folio, destinatario, asunto e id: se filtra la referencia exacta.
var lista = await Pedir($"/v1/correos?q={Uri.EscapeDataString(referencia)}&periodo=7d");
foreach (var resumen in lista.GetProperty("correos").EnumerateArray())
{
if (resumen.GetProperty("referencia").GetString() != referencia) continue;
var c = await Pedir($"/v1/correos/{Uri.EscapeDataString(resumen.GetProperty("id").GetString()!)}");
Console.WriteLine($"{c.GetProperty("id")} {c.GetProperty("referencia")} → {c.GetProperty("estado")}");
foreach (var d in c.GetProperty("destinatarios").EnumerateArray())
Console.WriteLine($" {d.GetProperty("tipo")} {d.GetProperty("email")}: {d.GetProperty("estado")}");
}
// Estado de un correo por id y búsqueda por folio (referencia).
// Java 17+ y Jackson (com.fasterxml.jackson.core:jackson-databind:2.17.2).
// export XRSEND_API_KEY="xrs_test_..." ; java -cp "jackson/*" Estado.java FAC-1234
// HTTP/1.1 explícito: así no intenta pasar a HTTP/2 sin TLS (h2c), que algunos proxies rechazan.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
public class Estado {
static final String URL = System.getenv().getOrDefault("XRSEND_URL", "https://api.xr-send.com");
static final ObjectMapper JSON = new ObjectMapper();
static final HttpClient HTTP = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
static JsonNode pedir(String ruta) throws Exception {
HttpRequest pet = HttpRequest.newBuilder(URI.create(URL + ruta)).timeout(Duration.ofSeconds(30))
.header("X-API-Key", System.getenv("XRSEND_API_KEY")).GET().build();
HttpResponse<String> r = HTTP.send(pet, HttpResponse.BodyHandlers.ofString());
JsonNode datos = JSON.readTree(r.body());
if (r.statusCode() != 200) throw new RuntimeException("HTTP " + r.statusCode() + ": " + datos.get("detail"));
return datos;
}
public static void main(String[] args) throws Exception {
String referencia = args.length > 0 ? args[0] : "FAC-1234";
// q busca en folio, destinatario, asunto e id: se filtra la referencia exacta.
JsonNode lista = pedir("/v1/correos?periodo=7d&q=" + URLEncoder.encode(referencia, StandardCharsets.UTF_8));
for (JsonNode resumen : lista.get("correos")) {
if (!referencia.equals(resumen.path("referencia").asText(null))) continue;
JsonNode c = pedir("/v1/correos/" + resumen.get("id").asText());
System.out.println(c.get("id").asText() + " " + c.get("referencia").asText() + " → " + c.get("estado").asText());
for (JsonNode d : c.get("destinatarios"))
System.out.println(" " + d.get("tipo").asText() + " " + d.get("email").asText() + ": " + d.get("estado").asText());
}
}
}
// Estado de un correo por id y búsqueda por folio (referencia).
// Node 18+. export XRSEND_API_KEY="xrs_test_..." ; node estado.mjs FAC-1234
const URL_API = process.env.XRSEND_URL ?? "https://api.xr-send.com";
const H = { "X-API-Key": process.env.XRSEND_API_KEY };
async function pedir(ruta) {
const r = await fetch(`${URL_API}${ruta}`, { headers: H });
const datos = await r.json();
if (r.status !== 200) throw new Error(`HTTP ${r.status}: ${JSON.stringify(datos.detail)}`);
return datos;
}
const referencia = process.argv[2] ?? "FAC-1234";
// q busca en folio, destinatario, asunto e id: se filtra la referencia exacta.
const lista = await pedir(`/v1/correos?${new URLSearchParams({ q: referencia, periodo: "7d" })}`);
for (const resumen of lista.correos.filter((c) => c.referencia === referencia)) {
const c = await pedir(`/v1/correos/${encodeURIComponent(resumen.id)}`);
console.log(`${c.id} ${c.referencia} → ${c.estado}`);
for (const d of c.destinatarios) console.log(` ${d.tipo} ${d.email}: ${d.estado}`);
}
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,InvensysoEn 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.
#!/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.
# 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.
# pip install requests ; export XRSEND_API_KEY_PRODUCCION="xr_..."
import os
import requests
URL = os.environ.get("XRSEND_URL", "https://api.xr-send.com")
NEGOCIO = os.environ.get("XRSEND_NEGOCIO", "ferreteria-lopez")
r = requests.post(f"{URL}/v1/negocios/{NEGOCIO}/webhooks", timeout=30,
headers={"X-API-Key": os.environ["XRSEND_API_KEY_PRODUCCION"]},
json={"url": os.environ.get("XRSEND_WEBHOOK_URL", "https://erp.tu-empresa.mx/webhooks/correo"),
"eventos": ["entregado", "rebotado", "queja", "no_enviado"],
"descripcion": "ERP producción"})
if r.status_code != 201:
raise SystemExit(f"HTTP {r.status_code}: {r.json().get('detail')}")
w = r.json()
print("webhook:", w["id"], w["url"], w["eventos"])
print("secreto (solo se muestra esta vez; guárdalo en tu vault):", w["secreto"])
<?php
// 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.
// export XRSEND_API_KEY_PRODUCCION="xr_..." ; php registrar_webhook.php (extensión curl)
$url = getenv('XRSEND_URL') ?: 'https://api.xr-send.com';
$negocio = getenv('XRSEND_NEGOCIO') ?: 'ferreteria-lopez';
$ch = curl_init("$url/v1/negocios/$negocio/webhooks");
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('XRSEND_API_KEY_PRODUCCION'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'url' => getenv('XRSEND_WEBHOOK_URL') ?: 'https://erp.tu-empresa.mx/webhooks/correo',
'eventos' => ['entregado', 'rebotado', 'queja', 'no_enviado'],
'descripcion' => 'ERP producción',
]),
]);
$w = json_decode(curl_exec($ch), true);
$codigo = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($codigo !== 201) {
exit("HTTP $codigo: " . json_encode($w['detail'] ?? null, JSON_UNESCAPED_UNICODE) . "\n");
}
echo "webhook: {$w['id']} {$w['url']}\n";
echo "secreto (solo se muestra esta vez; guárdalo en tu vault): {$w['secreto']}\n";
// 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.
// .NET 8, proyecto de consola con este archivo como Program.cs.
// export XRSEND_API_KEY_PRODUCCION="xr_..." ; dotnet run
using System.Net.Http.Json;
using System.Text.Json;
var url = Environment.GetEnvironmentVariable("XRSEND_URL") ?? "https://api.xr-send.com";
var negocio = Environment.GetEnvironmentVariable("XRSEND_NEGOCIO") ?? "ferreteria-lopez";
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("XRSEND_API_KEY_PRODUCCION"));
var r = await http.PostAsJsonAsync($"{url}/v1/negocios/{negocio}/webhooks", new
{
url = Environment.GetEnvironmentVariable("XRSEND_WEBHOOK_URL") ?? "https://erp.tu-empresa.mx/webhooks/correo",
eventos = new[] { "entregado", "rebotado", "queja", "no_enviado" },
descripcion = "ERP producción",
});
var w = await r.Content.ReadFromJsonAsync<JsonElement>();
if ((int)r.StatusCode != 201) throw new Exception($"HTTP {(int)r.StatusCode}: {w.GetProperty("detail")}");
Console.WriteLine($"webhook: {w.GetProperty("id")} {w.GetProperty("url")}");
Console.WriteLine($"secreto (solo se muestra esta vez; guárdalo en tu vault): {w.GetProperty("secreto")}");
// 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.
// Java 17+ y Jackson (com.fasterxml.jackson.core:jackson-databind:2.17.2).
// export XRSEND_API_KEY_PRODUCCION="xr_..." ; java -cp "jackson/*" RegistrarWebhook.java
// HTTP/1.1 explícito: así no intenta pasar a HTTP/2 sin TLS (h2c), que algunos proxies rechazan.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.List;
import java.util.Map;
public class RegistrarWebhook {
public static void main(String[] args) throws Exception {
String url = System.getenv().getOrDefault("XRSEND_URL", "https://api.xr-send.com");
String negocio = System.getenv().getOrDefault("XRSEND_NEGOCIO", "ferreteria-lopez");
ObjectMapper json = new ObjectMapper();
String cuerpo = json.writeValueAsString(Map.of(
"url", System.getenv().getOrDefault("XRSEND_WEBHOOK_URL", "https://erp.tu-empresa.mx/webhooks/correo"),
"eventos", List.of("entregado", "rebotado", "queja", "no_enviado"),
"descripcion", "ERP producción"));
HttpRequest pet = HttpRequest.newBuilder(URI.create(url + "/v1/negocios/" + negocio + "/webhooks"))
.timeout(Duration.ofSeconds(30))
.header("X-API-Key", System.getenv("XRSEND_API_KEY_PRODUCCION"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(cuerpo)).build();
HttpResponse<String> r = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build().send(pet, HttpResponse.BodyHandlers.ofString());
JsonNode w = json.readTree(r.body());
if (r.statusCode() != 201) throw new RuntimeException("HTTP " + r.statusCode() + ": " + w.get("detail"));
System.out.println("webhook: " + w.get("id").asText() + " " + w.get("url").asText());
System.out.println("secreto (solo se muestra esta vez; guárdalo en tu vault): " + w.get("secreto").asText());
}
}
// 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.
// Node 18+. export XRSEND_API_KEY_PRODUCCION="xr_..." ; node registrar-webhook.mjs
const URL_API = process.env.XRSEND_URL ?? "https://api.xr-send.com";
const negocio = process.env.XRSEND_NEGOCIO ?? "ferreteria-lopez";
const r = await fetch(`${URL_API}/v1/negocios/${negocio}/webhooks`, {
method: "POST",
headers: { "X-API-Key": process.env.XRSEND_API_KEY_PRODUCCION, "Content-Type": "application/json" },
body: JSON.stringify({
url: process.env.XRSEND_WEBHOOK_URL ?? "https://erp.tu-empresa.mx/webhooks/correo",
eventos: ["entregado", "rebotado", "queja", "no_enviado"],
descripcion: "ERP producción",
}),
});
const w = await r.json();
if (r.status !== 201) throw new Error(`HTTP ${r.status}: ${JSON.stringify(w.detail)}`);
console.log(`webhook: ${w.id} ${w.url}`);
console.log(`secreto (solo se muestra esta vez; guárdalo en tu vault): ${w.secreto}`);
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=.
- Lee el cuerpo crudo (no lo vuelvas a serializar: un espacio distinto cambia la firma).
- Rechaza si
X-XRSend-Fechaestá a más de 5 minutos de tu reloj (evita que repitan un aviso viejo). - Calcula
"sha256=" + hex(HMAC_SHA256(secreto, fecha + "." + cuerpo)). - Compárala con
X-XRSend-Firmaen tiempo constante. Si no coincide, responde 401 y no proceses. - Responde 2xx rápido (en menos de 10 s) y procesa después; usa
X-XRSend-Idpara no procesar dos veces.
Vector de prueba: secreto whsec_prueba, fecha 1700000000, cuerpo {"evento":"prueba"} →
sha256=66a878212ff983a02a3a40c45a2575a9fdf75a96ac7dc96e94c07a10ec53206c.
#!/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
# Receptor de webhooks con la biblioteca estándar (http.server). Verifica la firma sobre el cuerpo
# CRUDO, compara en tiempo constante y rechaza avisos de hace más de 5 minutos.
# export XRSEND_WEBHOOK_SECRETO="whsec_..." ; python webhook.py (escucha en el puerto 8080)
import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, HTTPServer
SECRETO = os.environ["XRSEND_WEBHOOK_SECRETO"]
TOLERANCIA_S = 300
procesados: set[str] = set() # en producción: tu base de datos (X-XRSend-Id ya visto)
def firma_valida(fecha: str, cuerpo: bytes, firma: str) -> bool:
if not fecha.isdigit() or abs(time.time() - int(fecha)) > TOLERANCIA_S:
return False
esperada = "sha256=" + hmac.new(SECRETO.encode(), fecha.encode() + b"." + cuerpo,
hashlib.sha256).hexdigest()
return hmac.compare_digest(esperada, firma)
class Receptor(BaseHTTPRequestHandler):
def do_POST(self):
cuerpo = self.rfile.read(int(self.headers.get("Content-Length", 0))) # bytes tal cual
if not firma_valida(self.headers.get("X-XRSend-Fecha", ""), cuerpo,
self.headers.get("X-XRSend-Firma", "")):
self.send_response(401)
self.end_headers()
return
self.send_response(200) # responde rápido; procesa después
self.end_headers()
aviso_id = self.headers["X-XRSend-Id"] # el mismo en cada reintento
if aviso_id in procesados:
return
procesados.add(aviso_id)
aviso = json.loads(cuerpo)
prueba = self.headers.get("X-XRSend-Prueba") == "1" # aviso de un correo de prueba
print(f"{aviso['evento']} {aviso['destinatario']} (folio {aviso.get('referencia')})"
f"{' [prueba]' if prueba else ''}: {aviso.get('causa')}", flush=True)
HTTPServer(("0.0.0.0", 8080), Receptor).serve_forever()
<?php
// Receptor de webhooks en PHP puro. Verifica la firma sobre el cuerpo CRUDO (php://input),
// compara en tiempo constante y rechaza avisos de hace más de 5 minutos.
// export XRSEND_WEBHOOK_SECRETO="whsec_..." ; php -S 0.0.0.0:8080 webhook.php
// En Laravel es lo mismo con $request->getContent() y $request->header('X-XRSend-Firma').
$secreto = getenv('XRSEND_WEBHOOK_SECRETO');
$cuerpo = file_get_contents('php://input'); // bytes tal como llegaron
$fecha = $_SERVER['HTTP_X_XRSEND_FECHA'] ?? '';
$firma = $_SERVER['HTTP_X_XRSEND_FIRMA'] ?? '';
$esperada = 'sha256=' . hash_hmac('sha256', $fecha . '.' . $cuerpo, $secreto);
if (!ctype_digit($fecha) || abs(time() - (int) $fecha) > 300 || !hash_equals($esperada, $firma)) {
http_response_code(401);
exit;
}
http_response_code(200); // responde rápido
// X-XRSend-Id es el mismo en cada reintento: guárdalo e ignora los que ya procesaste.
$avisoId = $_SERVER['HTTP_X_XRSEND_ID'] ?? '';
$prueba = ($_SERVER['HTTP_X_XRSEND_PRUEBA'] ?? '') === '1'; // aviso de un correo de prueba
$aviso = json_decode($cuerpo, true);
error_log("{$aviso['evento']} {$aviso['destinatario']} (folio {$aviso['referencia']})"
. ($prueba ? ' [prueba]' : '') . ": {$aviso['causa']}");
// Receptor de webhooks con ASP.NET Core minimal API (.NET 8, proyecto `dotnet new web` con este
// archivo como Program.cs). Verifica la firma sobre el cuerpo CRUDO, compara en tiempo constante
// y rechaza avisos de hace más de 5 minutos.
// export XRSEND_WEBHOOK_SECRETO="whsec_..." ; dotnet run --urls http://0.0.0.0:8080
using System.Collections.Concurrent;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
var secreto = Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("XRSEND_WEBHOOK_SECRETO")!);
var procesados = new ConcurrentDictionary<string, bool>(); // en producción: tu base de datos
var app = WebApplication.CreateBuilder(args).Build();
app.MapPost("/webhooks/correo", async (HttpRequest req) =>
{
using var ms = new MemoryStream();
await req.Body.CopyToAsync(ms);
var cuerpo = ms.ToArray(); // bytes tal como llegaron
string fecha = req.Headers["X-XRSend-Fecha"].ToString(), firma = req.Headers["X-XRSend-Firma"].ToString();
if (!long.TryParse(fecha, out var segundos) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - segundos) > 300)
return Results.Unauthorized();
var datos = Encoding.UTF8.GetBytes(fecha + ".").Concat(cuerpo).ToArray();
var esperada = "sha256=" + Convert.ToHexString(HMACSHA256.HashData(secreto, datos)).ToLowerInvariant();
if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(esperada), Encoding.UTF8.GetBytes(firma)))
return Results.Unauthorized();
// X-XRSend-Id es el mismo en cada reintento: ignora los que ya procesaste.
if (procesados.TryAdd(req.Headers["X-XRSend-Id"].ToString(), true))
{
var aviso = JsonDocument.Parse(cuerpo).RootElement;
var prueba = req.Headers["X-XRSend-Prueba"] == "1"; // aviso de un correo de prueba
Console.WriteLine($"{aviso.GetProperty("evento")} {aviso.GetProperty("destinatario")}{(prueba ? " [prueba]" : "")}: {aviso.GetProperty("causa")}");
}
return Results.Ok(); // responde rápido (en menos de 10 s)
});
app.Run();
// Receptor de webhooks con com.sun.net.httpserver (incluido en el JDK 17+, sin dependencias).
// Verifica la firma sobre el cuerpo CRUDO, compara en tiempo constante y rechaza avisos de hace
// más de 5 minutos. Con Spring Boot es igual: recibe el cuerpo como byte[] (@RequestBody byte[]).
// export XRSEND_WEBHOOK_SECRETO="whsec_..." ; java Webhook.java (escucha en el puerto 8080)
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
import java.io.ByteArrayOutputStream;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class Webhook {
static final byte[] SECRETO = System.getenv("XRSEND_WEBHOOK_SECRETO").getBytes(StandardCharsets.UTF_8);
static final Set<String> PROCESADOS = ConcurrentHashMap.newKeySet(); // en producción: tu base de datos
static boolean firmaValida(String fecha, byte[] cuerpo, String firma) throws Exception {
if (fecha == null || firma == null || !fecha.matches("\\d+")) return false;
if (Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(fecha)) > 300) return false;
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(SECRETO, "HmacSHA256"));
mac.update((fecha + ".").getBytes(StandardCharsets.UTF_8));
String esperada = "sha256=" + HexFormat.of().formatHex(mac.doFinal(cuerpo));
return MessageDigest.isEqual(esperada.getBytes(StandardCharsets.UTF_8), firma.getBytes(StandardCharsets.UTF_8));
}
static void recibir(HttpExchange ex) throws java.io.IOException {
try (ex) {
byte[] cuerpo = ex.getRequestBody().readAllBytes(); // bytes tal como llegaron
var h = ex.getRequestHeaders();
if (!"POST".equals(ex.getRequestMethod()) || !firmaValida(h.getFirst("X-XRSend-Fecha"), cuerpo, h.getFirst("X-XRSend-Firma"))) {
ex.sendResponseHeaders(401, -1);
return;
}
ex.sendResponseHeaders(200, -1); // responde rápido
// X-XRSend-Id es el mismo en cada reintento: ignora los que ya procesaste.
if (PROCESADOS.add(h.getFirst("X-XRSend-Id"))) {
boolean prueba = "1".equals(h.getFirst("X-XRSend-Prueba")); // aviso de un correo de prueba
System.out.println((prueba ? "[prueba] " : "") + new String(cuerpo, StandardCharsets.UTF_8));
}
} catch (Exception e) {
throw new java.io.IOException(e);
}
}
public static void main(String[] args) throws Exception {
HttpServer servidor = HttpServer.create(new InetSocketAddress(8080), 0);
servidor.createContext("/webhooks/correo", Webhook::recibir);
servidor.start();
}
}
// Receptor de webhooks con Express. express.raw entrega el cuerpo CRUDO (Buffer), que es sobre
// lo que se calcula la firma; se compara en tiempo constante y se rechazan avisos de hace más de 5 min.
// npm install express ; export XRSEND_WEBHOOK_SECRETO="whsec_..." ; node webhook.mjs (puerto 8080)
import crypto from "node:crypto";
import express from "express";
const SECRETO = process.env.XRSEND_WEBHOOK_SECRETO;
const procesados = new Set(); // en producción: tu base de datos (X-XRSend-Id ya visto)
function firmaValida(fecha, cuerpo, firma) {
if (!/^\d+$/.test(fecha ?? "") || Math.abs(Date.now() / 1000 - Number(fecha)) > 300) return false;
const esperada = "sha256=" + crypto.createHmac("sha256", SECRETO).update(`${fecha}.`).update(cuerpo).digest("hex");
const a = Buffer.from(esperada), b = Buffer.from(firma ?? "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
const app = express();
app.post("/webhooks/correo", express.raw({ type: "application/json" }), (req, res) => {
if (!firmaValida(req.get("X-XRSend-Fecha"), req.body, req.get("X-XRSend-Firma"))) {
return res.sendStatus(401);
}
res.sendStatus(200); // responde rápido; procesa después
const avisoId = req.get("X-XRSend-Id"); // el mismo en cada reintento
if (procesados.has(avisoId)) return;
procesados.add(avisoId);
const aviso = JSON.parse(req.body);
const prueba = req.get("X-XRSend-Prueba") === "1"; // aviso de un correo de prueba
console.log(`${aviso.evento} ${aviso.destinatario} (folio ${aviso.referencia})${prueba ? " [prueba]" : ""}: ${aviso.causa}`);
});
app.listen(8080);
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.
#!/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": […]}}
# Enviar con manejo de errores. Se reintenta solo 429, 5xx y fallas de red, con espera creciente
# y un poco de azar. Un 4xx (401, 403, 404, 409, 413, 422) volvería a fallar igual: no se reintenta.
# pip install requests ; export XRSEND_API_KEY="xrs_test_..."
import os
import random
import time
import requests
URL = os.environ.get("XRSEND_URL", "https://api.xr-send.com")
NEGOCIO = os.environ.get("XRSEND_NEGOCIO", "ferreteria-lopez")
class ErrorCorreo(Exception):
def __init__(self, codigo, detalle):
super().__init__(f"HTTP {codigo}: {detalle}")
self.codigo, self.detalle = codigo, detalle
def enviar(correo: dict, llave: str, intentos: int = 5) -> dict:
for intento in range(1, intentos + 1):
try:
r = requests.post(f"{URL}/v1/correos", json=correo, timeout=30, headers={"X-API-Key": llave})
except requests.RequestException as e: # sin respuesta: se puede reintentar
codigo, detalle = None, str(e)
else:
if r.status_code == 202:
return r.json() # éxito (también si duplicado: true)
codigo = r.status_code
try:
detalle = r.json().get("detail")
except ValueError:
detalle = r.text
if codigo == 429:
print(f"429: plan sin espacio (límite {detalle.get('limite')}, usados {detalle.get('usados')}, "
f"requeridos {detalle.get('requeridos')})" if isinstance(detalle, dict) else f"429: {detalle}")
elif codigo < 500:
raise ErrorCorreo(codigo, detalle) # 4xx: corregir, no reintentar
if intento == intentos:
raise ErrorCorreo(codigo, detalle)
espera = min(2 ** (intento - 1), 30) + random.random()
print(f"intento {intento} falló ({codigo}); reintento en {espera:.1f} s")
time.sleep(espera)
def explicar(e: ErrorCorreo) -> None:
if e.codigo == 401:
print("401: la llave falta, es inválida o la app está desactivada:", e.detalle)
elif e.codigo == 403:
print("403: negocio suspendido o plan desactivado; avisa al negocio:", e.detalle)
elif e.codigo == 404:
print("404: el negocio no existe o no está habilitado para tu sistema:", e.detalle)
elif e.codigo == 409:
print("409: conflicto:", e.detalle)
elif e.codigo == 413:
print("413: adjuntos demasiado grandes:", e.detalle)
elif e.codigo == 422 and isinstance(e.detalle, dict):
print("422:", e.detalle["mensaje"])
for o in e.detalle.get("omitidos", []):
print(f" {o['email']}: {o['motivo']}")
elif e.codigo == 422:
for campo in e.detalle: # validación: lista de campos
print("422:", ".".join(map(str, campo["loc"][1:])), "→", campo["msg"])
else:
print(e)
correo = {"negocio": NEGOCIO, "tipo": "factura", "para": "bloqueado@prueba.xr-send.com",
"asunto": "Tu factura FAC-1235", "texto": "Hola", "referencia": "FAC-1235"}
for llave in (os.environ["XRSEND_API_KEY"], "xrs_test_llave-equivocada"):
try:
print("aceptado:", enviar(correo, llave)["id"])
except ErrorCorreo as e:
explicar(e)
<?php
// Enviar con manejo de errores. Se reintenta solo 429, 5xx y fallas de red, con espera creciente
// y un poco de azar. Un 4xx (401, 403, 404, 409, 413, 422) volvería a fallar igual: no se reintenta.
// export XRSEND_API_KEY="xrs_test_..." ; php errores.php (extensión curl)
$url = getenv('XRSEND_URL') ?: 'https://api.xr-send.com';
class ErrorCorreo extends Exception {
public function __construct(public int $codigo, public mixed $detalle) {
parent::__construct("HTTP $codigo: " . json_encode($detalle, JSON_UNESCAPED_UNICODE));
}
}
function enviar(string $url, array $correo, string $llave, int $intentos = 5): array {
for ($i = 1; ; $i++) {
$ch = curl_init("$url/v1/correos");
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["X-API-Key: $llave", 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($correo),
]);
$cuerpo = curl_exec($ch);
$codigo = $cuerpo === false ? 0 : curl_getinfo($ch, CURLINFO_RESPONSE_CODE); // 0 = sin respuesta
$datos = $cuerpo === false ? null : json_decode($cuerpo, true);
if ($codigo === 202) {
return $datos; // éxito (también si duplicado: true)
}
$detalle = $datos['detail'] ?? ($cuerpo === false ? curl_error($ch) : $cuerpo);
if ($codigo === 429 && is_array($detalle)) {
echo "429: plan sin espacio (límite {$detalle['limite']}, usados {$detalle['usados']}, requeridos {$detalle['requeridos']})\n";
} elseif ($codigo >= 400 && $codigo < 500 && $codigo !== 429) {
throw new ErrorCorreo($codigo, $detalle); // 4xx: corregir, no reintentar
}
if ($i >= $intentos) {
throw new ErrorCorreo($codigo, $detalle);
}
$espera = min(2 ** ($i - 1), 30) + mt_rand(0, 1000) / 1000;
echo "intento $i falló ($codigo); reintento en {$espera} s\n";
usleep((int) ($espera * 1e6));
}
}
function explicar(ErrorCorreo $e): void {
$d = $e->detalle;
switch ($e->codigo) {
case 401: echo "401: la llave falta, es inválida o la app está desactivada: $d\n"; break;
case 403: echo "403: negocio suspendido o plan desactivado; avisa al negocio\n"; break;
case 404: echo "404: el negocio no existe o no está habilitado para tu sistema: $d\n"; break;
case 409: echo "409: conflicto: $d\n"; break;
case 413: echo "413: adjuntos demasiado grandes: $d\n"; break;
case 422:
if (isset($d['mensaje'])) {
echo "422: {$d['mensaje']}\n";
foreach ($d['omitidos'] ?? [] as $o) echo " {$o['email']}: {$o['motivo']}\n";
} else {
foreach ($d as $campo) echo '422: ' . implode('.', array_slice($campo['loc'], 1)) . " → {$campo['msg']}\n";
}
break;
default: echo $e->getMessage() . "\n";
}
}
$correo = ['negocio' => getenv('XRSEND_NEGOCIO') ?: 'ferreteria-lopez', 'tipo' => 'factura',
'para' => 'bloqueado@prueba.xr-send.com', 'asunto' => 'Tu factura FAC-1235',
'texto' => 'Hola', 'referencia' => 'FAC-1235'];
foreach ([getenv('XRSEND_API_KEY'), 'xrs_test_llave-equivocada'] as $llave) {
try {
echo 'aceptado: ' . enviar($url, $correo, $llave)['id'] . "\n";
} catch (ErrorCorreo $e) {
explicar($e);
}
}
// Enviar con manejo de errores. Se reintenta solo 429, 5xx y fallas de red, con espera creciente
// y un poco de azar. Un 4xx (401, 403, 404, 409, 413, 422) volvería a fallar igual: no se reintenta.
// .NET 8, proyecto de consola con este archivo como Program.cs.
// export XRSEND_API_KEY="xrs_test_..." ; dotnet run
using System.Net.Http.Json;
using System.Text.Json;
var url = Environment.GetEnvironmentVariable("XRSEND_URL") ?? "https://api.xr-send.com";
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
async Task<JsonElement> Enviar(object correo, string llave, int intentos = 5)
{
for (var i = 1; ; i++)
{
int codigo = 0;
JsonElement detalle = default;
try
{
using var pet = new HttpRequestMessage(HttpMethod.Post, $"{url}/v1/correos") { Content = JsonContent.Create(correo) };
pet.Headers.Add("X-API-Key", llave);
var r = await http.SendAsync(pet);
codigo = (int)r.StatusCode;
var datos = await r.Content.ReadFromJsonAsync<JsonElement>();
if (codigo == 202) return datos; // éxito (también si duplicado: true)
datos.TryGetProperty("detail", out detalle);
if (codigo == 429 && detalle.ValueKind == JsonValueKind.Object)
Console.WriteLine($"429: plan sin espacio (límite {detalle.GetProperty("limite")}, usados {detalle.GetProperty("usados")}, requeridos {detalle.GetProperty("requeridos")})");
else if (codigo < 500 && codigo != 429)
throw new ErrorCorreo(codigo, detalle); // 4xx: corregir, no reintentar
}
catch (Exception e) when (e is HttpRequestException or TaskCanceledException)
{
Console.WriteLine($"sin respuesta: {e.Message}"); // red o timeout: se puede reintentar
}
if (i >= intentos) throw new ErrorCorreo(codigo, detalle);
var espera = TimeSpan.FromSeconds(Math.Min(Math.Pow(2, i - 1), 30) + Random.Shared.NextDouble());
Console.WriteLine($"intento {i} falló ({codigo}); reintento en {espera.TotalSeconds:F1} s");
await Task.Delay(espera);
}
}
void Explicar(ErrorCorreo e)
{
var d = e.Detalle;
switch (e.Codigo)
{
case 401: Console.WriteLine($"401: la llave falta, es inválida o la app está desactivada: {d}"); break;
case 403: Console.WriteLine($"403: negocio suspendido o plan desactivado; avisa al negocio: {d}"); break;
case 404: Console.WriteLine($"404: el negocio no existe o no está habilitado para tu sistema: {d}"); break;
case 409: Console.WriteLine($"409: conflicto: {d}"); break;
case 413: Console.WriteLine($"413: adjuntos demasiado grandes: {d}"); break;
case 422 when d.ValueKind == JsonValueKind.Array: // validación: lista de campos
foreach (var c in d.EnumerateArray())
Console.WriteLine($"422: {string.Join(".", c.GetProperty("loc").EnumerateArray().Skip(1))} → {c.GetProperty("msg")}");
break;
case 422:
Console.WriteLine($"422: {d.GetProperty("mensaje")}");
if (d.TryGetProperty("omitidos", out var omitidos))
foreach (var o in omitidos.EnumerateArray())
Console.WriteLine($" {o.GetProperty("email")}: {o.GetProperty("motivo")}");
break;
default: Console.WriteLine(e.Message); break;
}
}
var correo = new
{
negocio = Environment.GetEnvironmentVariable("XRSEND_NEGOCIO") ?? "ferreteria-lopez",
tipo = "factura", para = "bloqueado@prueba.xr-send.com",
asunto = "Tu factura FAC-1235", texto = "Hola", referencia = "FAC-1235",
};
foreach (var llave in new[] { Environment.GetEnvironmentVariable("XRSEND_API_KEY")!, "xrs_test_llave-equivocada" })
{
try { Console.WriteLine($"aceptado: {(await Enviar(correo, llave)).GetProperty("id")}"); }
catch (ErrorCorreo e) { Explicar(e); }
}
class ErrorCorreo(int codigo, JsonElement detalle) : Exception($"HTTP {codigo}: {detalle}")
{
public int Codigo { get; } = codigo;
public JsonElement Detalle { get; } = detalle;
}
// Enviar con manejo de errores. Se reintenta solo 429, 5xx y fallas de red, con espera creciente
// y un poco de azar. Un 4xx (401, 403, 404, 409, 413, 422) volvería a fallar igual: no se reintenta.
// Java 17+ y Jackson (com.fasterxml.jackson.core:jackson-databind:2.17.2).
// export XRSEND_API_KEY="xrs_test_..." ; java -cp "jackson/*" Errores.java
// HTTP/1.1 explícito: así no intenta pasar a HTTP/2 sin TLS (h2c), que algunos proxies rechazan.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ThreadLocalRandom;
public class Errores {
static final String URL = System.getenv().getOrDefault("XRSEND_URL", "https://api.xr-send.com");
static final ObjectMapper JSON = new ObjectMapper();
static final HttpClient HTTP = HttpClient.newBuilder()
.version(HttpClient.Version.HTTP_1_1).connectTimeout(Duration.ofSeconds(10)).build();
static class ErrorCorreo extends Exception {
final int codigo;
final JsonNode detalle;
ErrorCorreo(int codigo, JsonNode detalle) {
super("HTTP " + codigo + ": " + detalle);
this.codigo = codigo;
this.detalle = detalle;
}
}
static JsonNode enviar(Map<String, Object> correo, String llave, int intentos) throws Exception {
for (int i = 1; ; i++) {
int codigo = 0;
JsonNode detalle = null;
try {
HttpRequest pet = HttpRequest.newBuilder(URI.create(URL + "/v1/correos"))
.timeout(Duration.ofSeconds(30)).header("X-API-Key", llave)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(JSON.writeValueAsString(correo))).build();
HttpResponse<String> r = HTTP.send(pet, HttpResponse.BodyHandlers.ofString());
codigo = r.statusCode();
JsonNode datos;
try {
datos = JSON.readTree(r.body());
} catch (IOException noEsJson) { // p. ej. una página de error de un proxy
datos = JSON.createObjectNode().put("detail", r.body());
}
if (codigo == 202) return datos; // éxito (también si duplicado: true)
detalle = datos.get("detail");
if (codigo == 429 && detalle != null && detalle.isObject())
System.out.println("429: plan sin espacio (límite " + detalle.get("limite") + ", usados "
+ detalle.get("usados") + ", requeridos " + detalle.get("requeridos") + ")");
else if (codigo < 500 && codigo != 429)
throw new ErrorCorreo(codigo, detalle); // 4xx: corregir, no reintentar
} catch (IOException e) {
System.out.println("sin respuesta: " + e); // red o timeout: se puede reintentar
}
if (i >= intentos) throw new ErrorCorreo(codigo, detalle);
long espera = (long) (Math.min(Math.pow(2, i - 1), 30) * 1000) + ThreadLocalRandom.current().nextLong(1000);
System.out.println("intento " + i + " falló (" + codigo + "); reintento en " + espera + " ms");
Thread.sleep(espera);
}
}
static void explicar(ErrorCorreo e) {
JsonNode d = e.detalle;
switch (e.codigo) {
case 401 -> System.out.println("401: la llave falta, es inválida o la app está desactivada: " + d.asText());
case 403 -> System.out.println("403: negocio suspendido o plan desactivado; avisa al negocio: " + d);
case 404 -> System.out.println("404: el negocio no existe o no está habilitado para tu sistema: " + d.asText());
case 409 -> System.out.println("409: conflicto: " + d.asText());
case 413 -> System.out.println("413: adjuntos demasiado grandes: " + d.asText());
case 422 -> {
if (d.isArray()) { // validación: lista de campos
for (JsonNode c : d) System.out.println("422: " + c.get("loc") + " → " + c.get("msg").asText());
} else {
System.out.println("422: " + d.get("mensaje").asText());
for (JsonNode o : d.path("omitidos"))
System.out.println(" " + o.get("email").asText() + ": " + o.get("motivo").asText());
}
}
default -> System.out.println(e.getMessage());
}
}
public static void main(String[] args) throws Exception {
Map<String, Object> correo = Map.of(
"negocio", System.getenv().getOrDefault("XRSEND_NEGOCIO", "ferreteria-lopez"),
"tipo", "factura", "para", "bloqueado@prueba.xr-send.com",
"asunto", "Tu factura FAC-1235", "texto", "Hola", "referencia", "FAC-1235");
for (String llave : List.of(System.getenv("XRSEND_API_KEY"), "xrs_test_llave-equivocada")) {
try {
System.out.println("aceptado: " + enviar(correo, llave, 5).get("id").asText());
} catch (ErrorCorreo e) {
explicar(e);
}
}
}
}
// Enviar con manejo de errores. Se reintenta solo 429, 5xx y fallas de red, con espera creciente
// y un poco de azar. Un 4xx (401, 403, 404, 409, 413, 422) volvería a fallar igual: no se reintenta.
// Node 18+. export XRSEND_API_KEY="xrs_test_..." ; node errores.mjs
const URL_API = process.env.XRSEND_URL ?? "https://api.xr-send.com";
class ErrorCorreo extends Error {
constructor(codigo, detalle) {
super(`HTTP ${codigo}: ${JSON.stringify(detalle)}`);
this.codigo = codigo;
this.detalle = detalle;
}
}
const dormir = (ms) => new Promise((ok) => setTimeout(ok, ms));
async function enviar(correo, llave, intentos = 5) {
for (let i = 1; ; i++) {
let codigo = 0, detalle;
try {
const r = await fetch(`${URL_API}/v1/correos`, {
method: "POST",
headers: { "X-API-Key": llave, "Content-Type": "application/json" },
body: JSON.stringify(correo),
signal: AbortSignal.timeout(30_000),
});
const datos = await r.json().catch(() => ({}));
if (r.status === 202) return datos; // éxito (también si duplicado: true)
codigo = r.status;
detalle = datos.detail;
if (codigo === 429 && typeof detalle === "object") {
console.log(`429: plan sin espacio (límite ${detalle.limite}, usados ${detalle.usados}, requeridos ${detalle.requeridos})`);
} else if (codigo < 500 && codigo !== 429) {
throw new ErrorCorreo(codigo, detalle); // 4xx: corregir, no reintentar
}
} catch (e) {
if (e instanceof ErrorCorreo) throw e;
detalle = String(e); // sin respuesta: se puede reintentar
}
if (i >= intentos) throw new ErrorCorreo(codigo, detalle);
const espera = Math.min(2 ** (i - 1), 30) * 1000 + Math.random() * 1000;
console.log(`intento ${i} falló (${codigo}); reintento en ${(espera / 1000).toFixed(1)} s`);
await dormir(espera);
}
}
function explicar(e) {
const d = e.detalle;
switch (e.codigo) {
case 401: return console.log("401: la llave falta, es inválida o la app está desactivada:", d);
case 403: return console.log("403: negocio suspendido o plan desactivado; avisa al negocio:", d);
case 404: return console.log("404: el negocio no existe o no está habilitado para tu sistema:", d);
case 409: return console.log("409: conflicto:", d);
case 413: return console.log("413: adjuntos demasiado grandes:", d);
case 422:
if (Array.isArray(d)) { // validación: lista de campos
for (const c of d) console.log(`422: ${c.loc.slice(1).join(".")} → ${c.msg}`);
} else {
console.log("422:", d.mensaje);
for (const o of d.omitidos ?? []) console.log(` ${o.email}: ${o.motivo}`);
}
return;
default: console.log(e.message);
}
}
const correo = {
negocio: process.env.XRSEND_NEGOCIO ?? "ferreteria-lopez", tipo: "factura",
para: "bloqueado@prueba.xr-send.com", asunto: "Tu factura FAC-1235", texto: "Hola", referencia: "FAC-1235",
};
for (const llave of [process.env.XRSEND_API_KEY, "xrs_test_llave-equivocada"]) {
try {
console.log("aceptado:", (await enviar(correo, llave)).id);
} catch (e) {
if (!(e instanceof ErrorCorreo)) throw e;
explicar(e);
}
}
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_diaconusados,limite,restantes; en planes por mes, tambiénuso_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.
#!/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"
# Uso del plan: hoy (y el mes, si el plan es mensual) y el consumo del mes por día.
# pip install requests ; export XRSEND_API_KEY="xrs_test_..."
import os
import requests
URL = os.environ.get("XRSEND_URL", "https://api.xr-send.com")
NEGOCIO = os.environ.get("XRSEND_NEGOCIO", "ferreteria-lopez")
H = {"X-API-Key": os.environ["XRSEND_API_KEY"]}
uso = requests.get(f"{URL}/v1/negocios/{NEGOCIO}/uso", headers=H, timeout=30).json()
hoy = uso["uso_dia"]
print(f"{uso['nombre']} (plan {uso['plan']}, {'activo' if uso['activo'] else 'suspendido'})")
print(f"hoy: {hoy['usados']} de {hoy['limite']} (quedan {hoy['restantes']})")
if "uso_mes" in uso: # solo en planes por mes
m = uso["uso_mes"]
print(f"mes: {m['usados']} de {m['limite']} (quedan {m['restantes']})")
mes = requests.get(f"{URL}/v1/negocios/{NEGOCIO}/uso-mensual", headers=H, timeout=30).json()
print(f"{mes['mes']}: {mes['correos']} correos, {mes['destinatarios']} destinatarios")
for dia in mes["por_dia"]:
print(f" {dia['fecha']}: {dia['destinatarios']}")
<?php
// Uso del plan: hoy (y el mes, si el plan es mensual) y el consumo del mes por día.
// export XRSEND_API_KEY="xrs_test_..." ; php uso.php (extensión curl)
$url = getenv('XRSEND_URL') ?: 'https://api.xr-send.com';
$negocio = getenv('XRSEND_NEGOCIO') ?: 'ferreteria-lopez';
function pedir(string $direccion): array {
$ch = curl_init($direccion);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('XRSEND_API_KEY')]]);
return json_decode(curl_exec($ch), true);
}
$uso = pedir("$url/v1/negocios/$negocio/uso");
$hoy = $uso['uso_dia'];
echo "{$uso['nombre']} (plan {$uso['plan']}, " . ($uso['activo'] ? 'activo' : 'suspendido') . ")\n";
echo "hoy: {$hoy['usados']} de {$hoy['limite']} (quedan {$hoy['restantes']})\n";
if (isset($uso['uso_mes'])) { // solo en planes por mes
$m = $uso['uso_mes'];
echo "mes: {$m['usados']} de {$m['limite']} (quedan {$m['restantes']})\n";
}
$mes = pedir("$url/v1/negocios/$negocio/uso-mensual");
echo "{$mes['mes']}: {$mes['correos']} correos, {$mes['destinatarios']} destinatarios\n";
foreach ($mes['por_dia'] as $dia) echo " {$dia['fecha']}: {$dia['destinatarios']}\n";
// Uso del plan: hoy (y el mes, si el plan es mensual) y el consumo del mes por día.
// .NET 8, proyecto de consola con este archivo como Program.cs.
// export XRSEND_API_KEY="xrs_test_..." ; dotnet run
using System.Net.Http.Json;
using System.Text.Json;
var url = Environment.GetEnvironmentVariable("XRSEND_URL") ?? "https://api.xr-send.com";
var negocio = Environment.GetEnvironmentVariable("XRSEND_NEGOCIO") ?? "ferreteria-lopez";
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("XRSEND_API_KEY"));
var uso = await http.GetFromJsonAsync<JsonElement>($"{url}/v1/negocios/{negocio}/uso");
var hoy = uso.GetProperty("uso_dia");
Console.WriteLine($"{uso.GetProperty("nombre")} (plan {uso.GetProperty("plan")}, {(uso.GetProperty("activo").GetBoolean() ? "activo" : "suspendido")})");
Console.WriteLine($"hoy: {hoy.GetProperty("usados")} de {hoy.GetProperty("limite")} (quedan {hoy.GetProperty("restantes")})");
if (uso.TryGetProperty("uso_mes", out var m)) // solo en planes por mes
Console.WriteLine($"mes: {m.GetProperty("usados")} de {m.GetProperty("limite")} (quedan {m.GetProperty("restantes")})");
var mes = await http.GetFromJsonAsync<JsonElement>($"{url}/v1/negocios/{negocio}/uso-mensual");
Console.WriteLine($"{mes.GetProperty("mes")}: {mes.GetProperty("correos")} correos, {mes.GetProperty("destinatarios")} destinatarios");
foreach (var dia in mes.GetProperty("por_dia").EnumerateArray())
Console.WriteLine($" {dia.GetProperty("fecha")}: {dia.GetProperty("destinatarios")}");
// Uso del plan: hoy (y el mes, si el plan es mensual) y el consumo del mes por día.
// Java 17+ y Jackson (com.fasterxml.jackson.core:jackson-databind:2.17.2).
// export XRSEND_API_KEY="xrs_test_..." ; java -cp "jackson/*" Uso.java
// HTTP/1.1 explícito: así no intenta pasar a HTTP/2 sin TLS (h2c), que algunos proxies rechazan.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Uso {
static final String URL = System.getenv().getOrDefault("XRSEND_URL", "https://api.xr-send.com");
static JsonNode pedir(String ruta) throws Exception {
HttpRequest pet = HttpRequest.newBuilder(URI.create(URL + ruta))
.header("X-API-Key", System.getenv("XRSEND_API_KEY")).GET().build();
return new ObjectMapper().readTree(HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build().send(pet, HttpResponse.BodyHandlers.ofString()).body());
}
public static void main(String[] args) throws Exception {
String negocio = System.getenv().getOrDefault("XRSEND_NEGOCIO", "ferreteria-lopez");
JsonNode uso = pedir("/v1/negocios/" + negocio + "/uso");
JsonNode hoy = uso.get("uso_dia");
System.out.println(uso.get("nombre").asText() + " (plan " + uso.get("plan").asText() + ", "
+ (uso.get("activo").asBoolean() ? "activo" : "suspendido") + ")");
System.out.println("hoy: " + hoy.get("usados") + " de " + hoy.get("limite") + " (quedan " + hoy.get("restantes") + ")");
if (uso.has("uso_mes")) { // solo en planes por mes
JsonNode m = uso.get("uso_mes");
System.out.println("mes: " + m.get("usados") + " de " + m.get("limite") + " (quedan " + m.get("restantes") + ")");
}
JsonNode mes = pedir("/v1/negocios/" + negocio + "/uso-mensual");
System.out.println(mes.get("mes").asText() + ": " + mes.get("correos") + " correos, " + mes.get("destinatarios") + " destinatarios");
for (JsonNode dia : mes.get("por_dia"))
System.out.println(" " + dia.get("fecha").asText() + ": " + dia.get("destinatarios"));
}
}
// Uso del plan: hoy (y el mes, si el plan es mensual) y el consumo del mes por día.
// Node 18+. export XRSEND_API_KEY="xrs_test_..." ; node uso.mjs
const URL_API = process.env.XRSEND_URL ?? "https://api.xr-send.com";
const negocio = process.env.XRSEND_NEGOCIO ?? "ferreteria-lopez";
const H = { "X-API-Key": process.env.XRSEND_API_KEY };
const pedir = async (ruta) => (await fetch(`${URL_API}${ruta}`, { headers: H })).json();
const uso = await pedir(`/v1/negocios/${negocio}/uso`);
const hoy = uso.uso_dia;
console.log(`${uso.nombre} (plan ${uso.plan}, ${uso.activo ? "activo" : "suspendido"})`);
console.log(`hoy: ${hoy.usados} de ${hoy.limite} (quedan ${hoy.restantes})`);
if (uso.uso_mes) { // solo en planes por mes
const m = uso.uso_mes;
console.log(`mes: ${m.usados} de ${m.limite} (quedan ${m.restantes})`);
}
const mes = await pedir(`/v1/negocios/${negocio}/uso-mensual`);
console.log(`${mes.mes}: ${mes.correos} correos, ${mes.destinatarios} destinatarios`);
for (const dia of mes.por_dia) console.log(` ${dia.fecha}: ${dia.destinatarios}`);
{"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.
#!/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"
# ¿Se le puede enviar a esta dirección? Úsalo al capturar el correo del cliente.
# pip install requests ; export XRSEND_API_KEY="xrs_test_..."
import os
import sys
from urllib.parse import quote
import requests
URL = os.environ.get("XRSEND_URL", "https://api.xr-send.com")
NEGOCIO = os.environ.get("XRSEND_NEGOCIO", "ferreteria-lopez")
H = {"X-API-Key": os.environ["XRSEND_API_KEY"]}
email = sys.argv[1] if len(sys.argv) > 1 else "cliente@gamil.com"
d = requests.get(f"{URL}/v1/supresiones/{quote(email, safe='@')}", headers=H, timeout=30).json()
if d["enviable"]:
print(email, "se puede usar")
else:
print(email, "NO:", d["motivo"])
if d.get("sugerencia"):
print(" sugerencia (confírmala con el cliente):", d["sugerencia"])
# Direcciones bloqueadas de los clientes del negocio (para pedirles otro correo)
lista = requests.get(f"{URL}/v1/negocios/{NEGOCIO}/supresiones", headers=H, timeout=30,
params={"limite": 50}).json()
print(f"{lista['total']} bloqueadas")
for s in lista["supresiones"]:
print(f" {s['email']}: {s['descripcion']}")
<?php
// ¿Se le puede enviar a esta dirección? Úsalo al capturar el correo del cliente.
// export XRSEND_API_KEY="xrs_test_..." ; php direccion.php cliente@gamil.com (extensión curl)
$url = getenv('XRSEND_URL') ?: 'https://api.xr-send.com';
$negocio = getenv('XRSEND_NEGOCIO') ?: 'ferreteria-lopez';
function pedir(string $direccion): array {
$ch = curl_init($direccion);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('XRSEND_API_KEY')]]);
return json_decode(curl_exec($ch), true);
}
$email = $argv[1] ?? 'cliente@gamil.com';
$d = pedir("$url/v1/supresiones/" . rawurlencode($email));
if ($d['enviable']) {
echo "$email se puede usar\n";
} else {
echo "$email NO: {$d['motivo']}\n";
if (!empty($d['sugerencia'])) echo " sugerencia (confírmala con el cliente): {$d['sugerencia']}\n";
}
// Direcciones bloqueadas de los clientes del negocio (para pedirles otro correo)
$lista = pedir("$url/v1/negocios/$negocio/supresiones?limite=50");
echo "{$lista['total']} bloqueadas\n";
foreach ($lista['supresiones'] as $s) echo " {$s['email']}: {$s['descripcion']}\n";
// ¿Se le puede enviar a esta dirección? Úsalo al capturar el correo del cliente.
// .NET 8, proyecto de consola con este archivo como Program.cs.
// export XRSEND_API_KEY="xrs_test_..." ; dotnet run -- cliente@gamil.com
using System.Net.Http.Json;
using System.Text.Json;
var url = Environment.GetEnvironmentVariable("XRSEND_URL") ?? "https://api.xr-send.com";
var negocio = Environment.GetEnvironmentVariable("XRSEND_NEGOCIO") ?? "ferreteria-lopez";
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("XRSEND_API_KEY"));
var email = args.Length > 0 ? args[0] : "cliente@gamil.com";
var d = await http.GetFromJsonAsync<JsonElement>($"{url}/v1/supresiones/{Uri.EscapeDataString(email)}");
if (d.GetProperty("enviable").GetBoolean())
Console.WriteLine($"{email} se puede usar");
else
{
Console.WriteLine($"{email} NO: {d.GetProperty("motivo")}");
if (d.TryGetProperty("sugerencia", out var s) && s.ValueKind == JsonValueKind.String)
Console.WriteLine($" sugerencia (confírmala con el cliente): {s}");
}
// Direcciones bloqueadas de los clientes del negocio (para pedirles otro correo)
var lista = await http.GetFromJsonAsync<JsonElement>($"{url}/v1/negocios/{negocio}/supresiones?limite=50");
Console.WriteLine($"{lista.GetProperty("total")} bloqueadas");
foreach (var b in lista.GetProperty("supresiones").EnumerateArray())
Console.WriteLine($" {b.GetProperty("email")}: {b.GetProperty("descripcion")}");
// ¿Se le puede enviar a esta dirección? Úsalo al capturar el correo del cliente.
// Java 17+ y Jackson (com.fasterxml.jackson.core:jackson-databind:2.17.2).
// export XRSEND_API_KEY="xrs_test_..." ; java -cp "jackson/*" Direccion.java cliente@gamil.com
// HTTP/1.1 explícito: así no intenta pasar a HTTP/2 sin TLS (h2c), que algunos proxies rechazan.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
public class Direccion {
static final String URL = System.getenv().getOrDefault("XRSEND_URL", "https://api.xr-send.com");
static JsonNode pedir(String ruta) throws Exception {
HttpRequest pet = HttpRequest.newBuilder(URI.create(URL + ruta))
.header("X-API-Key", System.getenv("XRSEND_API_KEY")).GET().build();
return new ObjectMapper().readTree(HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build().send(pet, HttpResponse.BodyHandlers.ofString()).body());
}
public static void main(String[] args) throws Exception {
String negocio = System.getenv().getOrDefault("XRSEND_NEGOCIO", "ferreteria-lopez");
String email = args.length > 0 ? args[0] : "cliente@gamil.com";
JsonNode d = pedir("/v1/supresiones/" + URLEncoder.encode(email, StandardCharsets.UTF_8).replace("+", "%20"));
if (d.get("enviable").asBoolean()) {
System.out.println(email + " se puede usar");
} else {
System.out.println(email + " NO: " + d.get("motivo").asText());
if (d.hasNonNull("sugerencia"))
System.out.println(" sugerencia (confírmala con el cliente): " + d.get("sugerencia").asText());
}
// Direcciones bloqueadas de los clientes del negocio (para pedirles otro correo)
JsonNode lista = pedir("/v1/negocios/" + negocio + "/supresiones?limite=50");
System.out.println(lista.get("total").asInt() + " bloqueadas");
for (JsonNode s : lista.get("supresiones"))
System.out.println(" " + s.get("email").asText() + ": " + s.get("descripcion").asText());
}
}
// ¿Se le puede enviar a esta dirección? Úsalo al capturar el correo del cliente.
// Node 18+. export XRSEND_API_KEY="xrs_test_..." ; node direccion.mjs cliente@gamil.com
const URL_API = process.env.XRSEND_URL ?? "https://api.xr-send.com";
const negocio = process.env.XRSEND_NEGOCIO ?? "ferreteria-lopez";
const H = { "X-API-Key": process.env.XRSEND_API_KEY };
const email = process.argv[2] ?? "cliente@gamil.com";
const d = await (await fetch(`${URL_API}/v1/supresiones/${encodeURIComponent(email)}`, { headers: H })).json();
if (d.enviable) {
console.log(`${email} se puede usar`);
} else {
console.log(`${email} NO: ${d.motivo}`);
if (d.sugerencia) console.log(` sugerencia (confírmala con el cliente): ${d.sugerencia}`);
}
// Direcciones bloqueadas de los clientes del negocio (para pedirles otro correo)
const lista = await (await fetch(`${URL_API}/v1/negocios/${negocio}/supresiones?limite=50`, { headers: H })).json();
console.log(`${lista.total} bloqueadas`);
for (const s of lista.supresiones) console.log(` ${s.email}: ${s.descripcion}`);
{"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):
- Nos dices el dominio o subdominio (te recomendamos un subdominio, como
facturas.cliente.com). - 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>conv=DMARC1; p=none; adkim=r; aspf=r(Gmail y Yahoo lo piden; súbelo aquarantinecuando todo esté bien). - 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).