API de email transaccional: el adjunto decide

En pocas palabras: Para enviar un reporte como guild-42-week-18.csv por API de email transaccional, primero exigí que la documentación vigente pruebe cómo viaja el adjunto; después verificá el dominio propio y publicá los registros DKIM antes de producción, y usá una clave de operación para que los reintentos no dupliquen el envío.

Una API de email transaccional sirve para un reporte con adjunto solo si documenta cómo viaja el archivo. Un artículo de dev.to del 7 de octubre de 2026 lo plantea como requisito de pasa o no pasa, antes de mirar plantillas, DKIM o webhooks.

Una API de email transaccional es una interfaz HTTP con la que una aplicación envía mensajes disparados por un evento, como un reporte semanal, y no campañas masivas. La app manda destinatario, plantilla y adjunto; el proveedor firma el mensaje con el dominio del remitente, lo entrega y después informa eventos como entrega o rebote. Acá el caso es el reporte semanal de un gremio de un juego, guardado como guild-42-week-18.csv.

¿Qué tiene que cumplir una API de email transaccional para mandar un reporte con adjunto?

Tiene que probar, en su documentación vigente, cuatro cosas: cómo se codifican los bytes del archivo, qué tipos y tamaños acepta, cómo evita duplicados y qué identificador une el envío con los eventos de entrega. Si falta una respuesta, el proveedor queda afuera. La fuente lo resume así (traducción nuestra): sin contrato de adjuntos, no hay selección.

• Codificación de los bytes. Cómo viaja el CSV dentro de la request, según el esquema publicado en la documentación del proveedor a la fecha en que lo evalúes (anotá esa fecha junto con la respuesta).
• Tipos y tamaños aceptados. Postmark, por ejemplo, documenta un máximo de 10 MB por email entre contenido, headers y adjuntos, con 50 destinatarios en total, según su documentación a la fecha de esta nota (7 de octubre de 2026). Los límites cambian: volvé a chequearlos y registrá la fecha de tu verificación.
• Prevención de duplicados. Si hay idempotencia, cómo se declara y cuánto dura.
• Identificador de seguimiento. El ID que después te sirve para consultar la entrega.

Ojo: no deduzcas nada del nombre de una ruta. Un endpoint que se llama “send” no te dice si acepta archivos.

El flujo completo que describe la fuente, en orden:

1. Verificás el dominio de envío y publicás DKIM.
2. Previsualizás la plantilla con datos incómodos.
3. El worker genera el reporte y crea una intención de envío inmutable.
4. Un adaptador traduce esa intención una sola vez al formato del proveedor.
5. Una reconciliación posterior registra el resultado final.

La fuente también compara cinco formas de integración en una revisión de documentación de una hora por candidato. Es una comparación de formas, no un ranking (y acá tampoco lo armamos). Los datos de Postmark salen de su documentación; el resto es lo que plantea el artículo. Tema relacionado: buenas prácticas para diseñar claves de API.

Opción	Qué mirar	Chequeo decisivo para este caso
Resend	API y SDK de Node.js/TypeScript; pide dominio propio verificado y API key	Límites de adjuntos, verificación de dominio, eventos
Postmark	API transaccional, plantillas, webhooks; 10 MB por email	Representación del adjunto y consumo de webhooks
Amazon SES	Envío por API/SDK con identidad y destinos de eventos	Cuánto hay que armar en plantillas y eventos
Otro proveedor	API de envío, plantillas dinámicas y webhook de eventos	Si toda esa superficie se justifica para un solo worker
Infrai	REST con una credencial; eventos por pull	Esquema de adjuntos, antes que nada

¿Qué hay que hacer antes de enviar el primer reporte: DKIM, dominio y plantilla?

Verificá el dominio de envío propio, publicá los registros DKIM que te indique el proveedor y esperá el estado “verificado” antes de mandar nada. Recién ahí tiene sentido probar la plantilla. Si gestionás el DNS de tu dominio en donweb.com, es ahí donde cargás esos registros.

DMARC es otra capa. Según el RFC 7489, es un mecanismo para que el dueño de un dominio publique su política y reciba reportes de los receptores, que comparan el dominio del From contra los resultados de SPF y DKIM. No firma nada. Detalle útil: la página del RFC Editor marca ese documento como obsoleto y remite a los RFC 9989, 9990 y 9991, así que conviene revisar la versión vigente.

Después, la plantilla. La fuente propone previsualizar la revisión weekly-report-v3 con datos adversos pero plausibles:

• Nombre para mostrar vacío.
• Nombre de gremio larguísimo.
• Texto de jugador con caracteres a escapar.
• Score opcional ausente.

Un ejemplo hipotético (los nombres de campo son inventados, no salen del esquema de ningún proveedor):

{
 "guild_name": "Los Inmortales del Sur Unidos por el Honor Eterno de la Patagonia",
 "display_name": "",
 "player_note": "Rey <b>\"Lucho\"</b> & co",
 "score": null
}

El código de la fuente llama a la operación documentada de preview con POST, lee la credencial de una variable de entorno, muestra el cuerpo de la respuesta cuando falla y respeta Retry-After ante un 429, con hasta cuatro reintentos y un respaldo de 500 ms multiplicado por 2 elevado al número de intento. Eso prueba acceso a la plantilla, manejo de errores y reintentos. No prueba que el adjunto viaje.

¿Cómo se evitan los envíos duplicados cuando hay un timeout?

Reutilizando la misma clave de operación después del timeout, en vez de crear un segundo envío lógico. La fuente la deriva de cinco datos: ID del gremio, período del reporte, destinatario, revisión de plantilla y hash SHA-256 del reporte. Ya lo cubrimos antes en cómo exponer una herramienta CLI como API.

Ponele que el proveedor tarda en responder, tu código vence el timeout, el worker reintenta la función entera, regenera el CSV con otro timestamp adentro, vuelve a mandar y el capitán del gremio recibe dos mails con archivos que no coinciden, sin que ninguno de tus logs te diga cuál es el bueno. Ese escenario es el que el modelo de la fuente evita: el worker crea una intención de envío inmutable, el adaptador la traduce una vez y la reconciliación cierra el ciclo.

Guardá tres valores y nada más:

• Clave de operación. Identifica el envío lógico.
• SHA-256 del reporte. Distingue un archivo regenerado de uno repetido.
• ID de mensaje del proveedor. Sirve para consultar el estado de entrega.

Con esos tres alcanza, sin loguear el contenido del reporte. Probá además un adjunto cerca del límite documentado y otro por encima; el adaptador tiene que rechazar el segundo antes de hacer la request.

Sobre Infrai, el autor sostiene que documenta la idempotencia como convención de plataforma, con una ventana de deduplicación de 24 horas por defecto, y que 171 de 294 capacidades descubiertas están marcadas como idempotentes. Antes de aplicarlo a un envío, la propia fuente pide verificar el esquema vivo de esa capacidad. Inferencia nuestra: si reintentás pasadas las 24 horas, esa ventana ya no te cubre, así que el estado conviene llevarlo en tu base.

¿Alcanza con consultar eventos por polling o necesito webhooks?

Para un reporte semanal informativo, alcanza con una reconciliación programada. Si necesitás reaccionar de inmediato a un rebote duro, conviene un proveedor con push documentado. Más contexto en organizar los cambios con PRs apilados.

• Polling. No hay receptor entrante que asegurar, pero gastás requests y detectás los problemas más tarde.
• Webhooks. Reaccionás más rápido, a cambio de un receptor público y de verificar firmas. Según la fuente, Resend y Postmark documentan webhooks (Postmark lista entrega, rebote, queja de spam, aperturas y clics) y Amazon SES documenta destinos de eventos.
• Infrai. Es solo pull, con listado de eventos y sin webhook de entrega.

Para monitorear, la fuente sugiere guardar el ID del mensaje, consultar en una ventana acotada y cortar al llegar a un estado terminal o a un vencimiento. Sumá un contador de resultados finales y un gauge de mensajes más viejos que la ventana esperada. Alertá por un corrimiento sostenido de la tasa de rebote, no por un mensaje suelto.

Las aperturas, aparte. Según el mismo artículo, Apple Mail Privacy Protection puede cargar contenido remoto de una manera que oculta el comportamiento normal de apertura, así que un “abierto” no prueba que alguien leyó el reporte. Medí el uso real dentro del juego o la web autenticada.

¿Qué dice y qué no dice la evidencia sobre Infrai y los adjuntos?

La fuente no establece que Infrai soporte adjuntos. Declara como verificado el resto del flujo básico, pero el campo de adjuntos queda sin confirmar, y el propio autor dice que para este trabajo hay que revisar el esquema vivo antes de elegirlo.

Qué declara la fuente como verificado

• Verificación de dominio, creación y preview de plantillas, envío directo por API y listado de eventos.
• 295 rutas en 20 módulos detrás de una sola clave y un contrato REST.
• Sin relé SMTP: el código de tu aplicación hace la llamada.
• Flujos transaccionales básicos de EE. UU. y Europa.

Qué no está establecido o tiene límites

• Adjuntos: sin evidencia en el contrato verificado.
• OTP por email: no hay uno gestionado; generación, vencimiento y límite de intentos quedan de tu lado.
• Email programado: no se puede cancelar, así que la cola conviene mantenerla en tu aplicación y llamar al proveedor cuando toque.
• China continental: el proveedor de email figura como pendiente.

Las cifras (295 rutas, 171 de 294 idempotentes, ejemplos en 10 lenguajes) son declaraciones del autor y no encontramos confirmación independiente. Tomalas con pinzas. Y si la documentación vigente de Resend, Postmark o Amazon SES prueba el contrato de adjuntos y la de Infrai no, elegí el que lo prueba. Relacionado: probar el entorno local en Mac.

Cómo verificarlo (propuesta editorial)

Esto no sale de la fuente y no lo probamos: antes de pedir credenciales, leé el esquema de la request de cada candidato y respondé por escrito las cuatro preguntas del primer apartado, con un CSV de ejemplo y otro que supere el límite documentado. Anotá la fecha en que consultaste cada documentación. Cualquier “no documentado” descarta al candidato.

Errores comunes

• Elegir por la plantilla y mirar los adjuntos al final. Corrección: el adjunto va primero, porque es lo único que puede descartar al proveedor.
• Reintentar la función entera tras un timeout. Corrección: reintentá solo el envío, con la misma clave y el mismo archivo.
• Creer que DMARC reemplaza a DKIM. Corrección: DKIM firma, DMARC agrega política y reportes.
• Tomar las aperturas como lectura. Corrección: con Apple Mail Privacy Protection no prueban nada; medí dentro de la app.
• Loguear el reporte para depurar. Corrección: con la clave, el SHA-256 y el ID del proveedor ya podés reconstruir qué pasó.

Preguntas Frecuentes

¿Cómo envío un archivo adjunto con una API de email transaccional?

Depende del contrato que documente tu proveedor: cómo codifica los bytes, qué tipos acepta y qué tamaño máximo permite. Postmark, por ejemplo, documenta 10 MB por email entre contenido, headers y adjuntos, según su documentación a la fecha de esta nota (7 de octubre de 2026). Leé el esquema vigente antes de escribir código.

¿Hay que verificar DKIM antes de enviar emails desde mi propio dominio?

Sí, según la fuente: verificá el dominio, publicá los registros DKIM y esperá el estado verificado antes de producción. DMARC se suma después como política y reporte, pero no sustituye la firma.

¿Cómo evito que un reintento mande el mismo email dos veces?

Derivá una clave de operación de gremio, período, destinatario, revisión de plantilla y SHA-256 del reporte, y reutilizala tras un timeout. Sirve solo si el proveedor documenta idempotencia, así que confirmá su esquema vivo.

¿Sirve el polling de eventos o necesito webhooks para saber si se entregó un email?

El polling sirve si el reporte es informativo y tolera demora en la reconciliación. Para reaccionar enseguida a un rebote duro necesitás un proveedor con webhooks documentados, que a cambio te piden un receptor público y verificación de firmas.

¿Las aperturas de email son confiables con Apple Mail Privacy Protection?

No. Según la fuente, esa función puede cargar contenido remoto y volver opaco el comportamiento de apertura. Tratá entrega y rebote como telemetría de transporte y medí el uso real dentro del juego o la web autenticada.

Conclusión

El criterio de la fuente es corto: descartá al proveedor que no pruebe el contrato de adjuntos y, entre los que queden, quedate con el que menos piezas operativas te sume. DKIM, reintentos deterministas y evidencia de entrega forman parte de esa cuenta. La llamada de envío es una línea más.

Sobre Infrai, hoy la evidencia alcanza para un flujo básico sin adjuntos, no para el reporte con CSV. Antes de decidir, revisá el esquema en vivo de tu candidato con la lista de cuatro preguntas.

Fuentes

• dev.to – Transactional Game Report Email API with Custom-Domain DKIM (A Template-First Setup), fuente original
• RFC Editor – RFC 7489, DMARC (marcado como obsoleto)
• Resend – documentación de la API
• Postmark – documentación para desarrolladores
• AWS – documentación de Amazon SES