Mail transaccional
Mail transaccional por API, en la misma cuenta que tus campañas
Confirmación de pedido, recuperación de contraseña y aviso de cobro saliendo de tu sistema por una API REST, en el mismo medidor que tus campañas.
Qué es el mail transaccional
El mail transaccional es el mensaje que tu sistema le envía a una persona por algo que ella hizo: creó una cuenta, compró, pidió cambiar la contraseña, recibió un cobro. Va a un destinatario por vez, en el momento del evento, y la persona espera recibirlo.
El email marketing es lo contrario: el mismo mensaje para una lista, en el horario que elige la empresa. Por eso los dos suelen estar en herramientas separadas, con dos facturas y dos paneles para seguir la entrega.
| Transaccional | Marketing | |
|---|---|---|
| Quién lo envía | Tu sistema, por API | Vos, desde el panel |
| Para quién | Una persona por vez | Una lista o segmento |
| Cuándo | En el momento del evento | En el horario elegido |
| Ejemplos | Contraseña, pedido, factura, código de acceso | Newsletter, promoción, lanzamiento |
| Baja | No aplica a mensajes de servicio | Obligatoria, en un clic |
En WiseData Mail los dos salen de la misma cuenta, del mismo dominio autenticado y cuentan en el mismo medidor de envíos.
Dos formas de enviar por la API
Elegí una plantilla creada en la plataforma o mandá el contenido listo en la llamada. La respuesta llega en el momento; la entrega llega después, por el webhook.
- Plantilla de la plataforma: creá el mail transaccional en el panel y la llamada lleva solo la clave de la plantilla y las variables (nombre, número de pedido, link). Cambiar el texto no te obliga a tocar tu sistema.
- Contenido en la llamada: si preferís mantener el mail en tu propio código, mandá el asunto, el HTML y la versión en texto directo a la API.
- 202 cuando el mensaje entra en la cola; 200 cuando la misma clave de idempotencia ya se usó, sin enviar de nuevo.
- Hasta 10 adjuntos por mensaje, con un total de 10 MB, también junto con una plantilla de la plataforma: la confirmación guardada en el panel, con el PDF de la factura en la llamada.
- Las etiquetas y los metadatos vuelven en cada evento de webhook, para que vincules la entrega con el pedido.
Ejemplos de mail transaccional
Los seis tipos que casi todo sistema necesita enviar, cada uno con el cuidado que evita el problema más común.
Registro y confirmación de mail
Bienvenida y enlace para confirmar la dirección justo después del registro. Consejo: el enlace tiene que vencer y funcionar una sola vez. Envialo en el momento del registro, nunca en lote al final del día.
Recuperación de contraseña
Enlace para crear una contraseña nueva. Consejo: validez corta, un solo uso y ninguna contraseña en el cuerpo. En la pantalla de "olvidé mi contraseña", mostrá el mismo mensaje exista o no la cuenta.
Código de acceso
Código de verificación en dos pasos o de inicio de sesión sin contraseña. Consejo: el código va en el cuerpo, nunca en el asunto, porque el asunto aparece en la notificación de la pantalla bloqueada.
Confirmación de pedido
Número de pedido, artículos, total y próximos pasos. Consejo: usá el id del pedido en la Idempotency-Key. Si tu sistema repite la llamada, el cliente no recibe dos confirmaciones.
Cobro, factura y recibo
Factura, comprobante de pago, recibo y aviso de vencimiento. Consejo: adjuntá el PDF (hasta 10 MB en total) o mandá un enlace al área con sesión iniciada. Guardá el id de la factura en los metadatos para conciliar por el webhook.
Aviso del sistema
Nuevo acceso a la cuenta, cambio de mail, cambio de términos, falla en una integración. Consejo: decí qué pasó y qué tiene que hacer la persona, con un solo botón. Sin promociones.
Cómo funciona la entrega
De la llamada a la API hasta que el evento llega a tu sistema, en cuatro pasos.
Tu sistema llama a la API
POST /v1/emails con la clave de la API. La respuesta 202 trae el identificador del mensaje; con la misma Idempotency-Key, la respuesta es 200 y no sale nada de nuevo.
La cuenta verifica antes de enviar
Una dirección ya suprimida por rebote permanente o queja vuelve con el estado suppressed. Sin cuota en el ciclo, la API rechaza la llamada con 403 en lugar de encolarla.
El mensaje sale por tu dominio
Firmado con el DKIM de tu dominio autenticado. El proveedor del destinatario lo acepta (entrega) o lo rechaza (rebote), y el resultado se convierte en evento.
Los eventos llegan al webhook
Entrega, apertura, clic, rebote, queja y baja, en lotes de hasta cien, firmados y con reintento automático si tu servidor no responde.
Los eventos del webhook
Cada evento trae el tipo, la hora, la dirección, el identificador del mensaje y las etiquetas y metadatos que enviaste con el mensaje. El campo campaign_id viene nulo en el transaccional, y message_type indica si el mensaje era transactional o marketing.
| Evento | Cuándo llega | Qué hacer |
|---|---|---|
| delivered | El proveedor del destinatario aceptó el mensaje | Marcarlo como entregado en tu sistema |
| bounce | El mensaje fue rechazado; bounce_classification indica el motivo | Si es definitivo, pedirle otra dirección a la persona |
| spamreport | El destinatario lo marcó como spam | No reenviar; la dirección ya fue suprimida |
| open | El mensaje se abrió; machine_open marca las aperturas de antivirus y precarga | Dejar las automáticas fuera de tu tasa de apertura |
| click | Se hizo clic en un enlace; el campo url indica cuál | Vincular el clic al registro por los metadatos |
| unsubscribe | El destinatario pidió la baja | Reflejar la preferencia en tus propios registros |
Los eventos llegan en lotes de hasta cien, firmados con el secreto del endpoint. El ejemplo completo de un lote está en el Centro de Ayuda.
Los resultados simulados por la bandeja de pruebas llegan al mismo endpoint, firmados de la misma forma, con is_test: true. Filtrá por ese campo para que un rebote de prueba nunca dé de baja a un cliente real.
Buenas prácticas de mail transaccional
El transaccional es el mail que la persona está esperando. Si cae en spam o llega dos veces, el problema se convierte en un ticket de soporte. Estas seis prácticas resuelven la mayoría de los casos.
1. Remitente separado del marketing
Usá una dirección propia para el transaccional, como pedidos@ o cuenta@, y no la misma del newsletter. Si tu plan incluye más de un dominio, un subdominio solo para el transaccional (por ejemplo, avisos.tuempresa.com.ar) separa la reputación de los dos ante los proveedores de correo: una campaña con muchas quejas no arrastra la recuperación de contraseña a spam.
2. Asunto sin datos sensibles
El asunto aparece en la notificación del celular, en la lista de la bandeja de entrada y en los registros de quien procesa el mail. Nada de código de acceso, contraseña, número de documento o de tarjeta en el asunto. "Tu código de acceso" alcanza; el código va en el cuerpo.
3. Siempre con versión en texto
Enviá el campo text junto con html. Los lectores de pantalla, los relojes y algunos clientes de correo corporativos muestran la versión en texto, y que falte le juega en contra al mensaje en los filtros de spam.
4. Idempotencia en cada llamada
Una cola que reintenta, un timeout que dispara un nuevo intento y un doble clic en el botón generan la misma llamada dos veces. Derivá la Idempotency-Key del identificador interno (pedido-48213-confirmacion) y reutilizá la misma clave en cada reintento. La API devuelve el mensaje anterior con 200 y no envía otro.
5. Webhook tratado de la forma correcta
- Verificá la firma: HMAC-SHA256 del timestamp, un punto y el cuerpo sin procesar, con el secreto del endpoint, comparado con el encabezado X-WiseData-Signature.
- Rechazá timestamps antiguos, para que un lote capturado no se reutilice después.
- Respondé 2xx rápido y procesá en una cola. Una respuesta lenta se convierte en reintento.
- Descartá repeticiones por X-WiseData-Delivery (el lote) y por el id de cada evento.
- No asumas un orden: usá occurred_at para no reemplazar un estado más nuevo por uno más viejo.
6. No mezcles marketing en el transaccional
Un banner de promoción en el pie de la confirmación de pedido convierte el mensaje de servicio en un mensaje comercial: pasa a exigir baja y consentimiento, y las quejas que genere caen sobre el canal que entrega la contraseña. Las promociones van por campaña, para quien aceptó recibirlas.
¿Tu dominio todavía no está autenticado? Leé la guía de SPF, DKIM y DMARC.
Lo que viene con la API
Webhooks firmados
Entrega, apertura, clic, rebote, queja y baja llegan en lotes de hasta cien eventos, con firma, reintento automático y rotación de secreto.
Bandeja de pruebas
Una clave de prueba simula entrega, rebote y queja sin enviar nada hacia afuera. Podés probar el receptor de webhooks antes de pasar a producción.
Claves con alcance
Cada clave recibe solo lo que necesita: leer contactos, escribir contactos, eliminar contactos o enviar mails.
Contactos por la misma API
Creá o corregí contactos con el identificador de tu sistema y sumalos a listas, para que las campañas usen la misma base.
Aperturas automáticas marcadas
Las aperturas y los clics hechos por antivirus o precarga vienen marcados, para no inflar tus números.
SDK PHP y transport para Laravel
Cliente PHP de código abierto (MIT). En Laravel, el envío pasa por WiseData Mail cambiando el mailer en el .env.
Por qué tener los dos en una sola cuenta
- Marketing y transaccional con el mismo proveedor y en el mismo medidor.
- Verificación previa al envío y panel de salud también para el transaccional.
- Reputación de envío aislada por cuenta: el problema de otro cliente no afecta tu entrega.
- Contactos ilimitados y sin cobro por excedente: si agotás la cuota, el envío se pausa en lugar de cobrarte de más.
En qué planes
La API está incluida en el plan Volume (R$ 799, 400 mil envíos). La prueba gratuita no incluye la API.
Ver los planesPreguntas sobre mail transaccional
¿Cuál es la diferencia entre mail transaccional y email marketing?
El transaccional lo dispara tu sistema por algo que hizo la persona (registro, compra, cambio de contraseña) y va a un destinatario por vez. El marketing es el mismo mensaje para una lista, en el horario que elige la empresa. En WiseData Mail los dos salen de la misma cuenta.
¿El mail transaccional necesita consentimiento?
Un mensaje de servicio, vinculado a una cuenta, un pedido o un contrato, no depende del consentimiento de marketing y no exige baja. Eso vale mientras siga siendo solo de servicio: con una promoción adentro, pasa a ser mail comercial.
¿Tienen SMTP?
No. El envío es por la API REST y por el panel. En Laravel, el SDK PHP reemplaza al SMTP sin cambiar el código que llama a Mail.
¿El mail transaccional tiene baja?
Los mensajes de servicio, como contraseña y pedido, no exigen baja. Si la dirección ya está suprimida por rebote permanente o queja, la API devuelve el estado suppressed en lugar de enviar.
¿Cómo evito enviar dos veces el mismo mensaje?
Enviá el encabezado Idempotency-Key. Si la misma clave llega de nuevo, la API devuelve el mensaje anterior con estado 200 y no envía otro.
¿Cómo sé si el mail fue entregado?
Por el webhook, que envía el evento delivered cuando el proveedor del destinatario acepta el mensaje y bounce cuando lo rechaza. En el panel, la línea de tiempo del contacto muestra cada envío y el motivo de cada falla.
¿Puedo probar la integración sin enviar a clientes reales?
Sí. La clave de prueba de la bandeja de pruebas simula entrega, rebote y queja sin enviar nada hacia afuera, y los eventos llegan a tu webhook con is_test: true.
¿Cuánto cuesta el mail transaccional?
Cada mensaje cuenta como un envío en el mismo medidor que tus campañas. La API está en el plan Volume, R$ 799 por mes con 400 mil envíos. Si agotás la cuota, la API rechaza nuevos envíos hasta el próximo ciclo: no existe cobro por excedente.
Empezá por la prueba gratuita
Conocé el panel y autenticá tu dominio sin tarjeta. La API y la bandeja de pruebas vienen en el plan Volume.