Correo transaccional

Correo transaccional por API, en la misma cuenta que sus campañas

Confirmación de pedido, restablecimiento de contraseña y aviso de cobro saliendo de su sistema por una API REST, en el mismo medidor que sus campañas.

Qué es el correo transaccional

El correo transaccional es el mensaje que su sistema 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 a la 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.

Diferencia entre correo transaccional y email marketing
TransaccionalMarketing
Quién lo envíaSu sistema, por APIUsted, desde el panel
Para quiénUna persona a la vezUna lista o segmento
CuándoEn el momento del eventoEn el horario elegido
EjemplosContraseña, pedido, boleto de pago, código de accesoBoletín, promoción, lanzamiento
BajaNo aplica a mensajes de servicioObligatoria, 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

Elija una plantilla creada en la plataforma o envíe el contenido listo en la llamada. La respuesta llega en el momento; la entrega llega después, por el webhook.

  • Plantilla de la plataforma: cree el correo transaccional en el panel y la llamada lleva solo la clave de la plantilla y las variables (nombre, número de pedido, enlace). Cambiar el texto no exige tocar su sistema.
  • Contenido en la llamada: si prefiere mantener el correo en su propio código, envíe 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 usted vincule la entrega con el pedido.

Ejemplos de correo 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 correo

    Bienvenida y enlace para confirmar la dirección justo después del registro. Consejo: el enlace debe vencer y funcionar una sola vez. Envíelo en el momento del registro, nunca en lote al final del día.

  • Restablecimiento 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", muestre 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: use el id del pedido en la Idempotency-Key. Si su sistema repite la llamada, el cliente no recibe dos confirmaciones.

  • Cobro, factura y recibo

    Factura, boleto de pago, recibo y aviso de vencimiento. Consejo: adjunte el PDF (hasta 10 MB en total) o envíe un enlace al área con sesión iniciada. Guarde el id de la factura en los metadatos para conciliar por el webhook.

  • Aviso del sistema

    Nuevo acceso a la cuenta, cambio de correo, cambio de términos, falla en una integración. Consejo: diga qué pasó y qué debe 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 su sistema, en cuatro pasos.

  1. Su 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.

  2. 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.

  3. El mensaje sale por su dominio

    Firmado con el DKIM de su dominio autenticado. El proveedor del destinatario lo acepta (entrega) o lo rechaza (rebote), y el resultado se convierte en evento.

  4. Los eventos llegan al webhook

    Entrega, apertura, clic, rebote, queja y baja, en lotes de hasta cien, firmados y con reintento automático si su 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 usted envió con el mensaje. El campo campaign_id viene nulo en el transaccional, y message_type indica si el mensaje era transactional o marketing.

Tipos de evento del webhook y qué hacer con cada uno
EventoCuándo llegaQué hacer
deliveredEl proveedor del destinatario aceptó el mensajeMarcarlo como entregado en su sistema
bounceEl mensaje fue rechazado; bounce_classification indica el motivoSi es definitivo, pedir otra dirección a la persona
spamreportEl destinatario lo marcó como spamNo reenviar; la dirección ya fue suprimida
openEl mensaje se abrió; machine_open marca las aperturas de antivirus y precargaDejar las automáticas fuera de su tasa de apertura
clickSe hizo clic en un enlace; el campo url indica cuálVincular el clic al registro por los metadatos
unsubscribeEl destinatario pidió la bajaReflejar la preferencia en sus 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. Filtre por ese campo para que un rebote de prueba nunca dé de baja a un cliente real.

Buenas prácticas de correo transaccional

El transaccional es el correo 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

Use una dirección propia para el transaccional, como pedidos@ o cuenta@, y no la misma del boletín. Si su plan incluye más de un dominio, un subdominio solo para el transaccional (por ejemplo, avisos.suempresa.com) separa la reputación de los dos ante los proveedores de correo: una campaña con muchas quejas no arrastra el restablecimiento 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 correo. Nada de código de acceso, contraseña, número de documento o de tarjeta en el asunto. "Su código de acceso" es suficiente; el código va en el cuerpo.

3. Siempre con versión en texto

Envíe 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 su ausencia juega en contra del 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. Derive la Idempotency-Key del identificador interno (pedido-48213-confirmacion) y reutilice 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

  • Verifique 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.
  • Rechace timestamps antiguos, para que un lote capturado no se reutilice después.
  • Responda 2xx rápido y procese en una cola. Una respuesta lenta se convierte en reintento.
  • Descarte repeticiones por X-WiseData-Delivery (el lote) y por el id de cada evento.
  • No asuma un orden: use occurred_at para no reemplazar un estado más nuevo por uno más viejo.

6. No mezcle 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.

¿Su dominio todavía no está autenticado? Lea 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. Puede 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 correos.

  • Contactos por la misma API

    Cree o corrija contactos con el identificador de su sistema y agréguelos 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 sus 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 su entrega.
  • Contactos ilimitados y sin cobro por excedente: al agotar la cuota, el envío se pausa en lugar de cobrar 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 planes

Preguntas sobre correo transaccional

¿Cuál es la diferencia entre correo transaccional y email marketing?

El transaccional lo dispara su sistema por algo que hizo la persona (registro, compra, cambio de contraseña) y va a un destinatario a la 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 correo 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 dentro, pasa a ser correo 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 correo 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?

Envíe 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 correo 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 su webhook con is_test: true.

¿Cuánto cuesta el correo transaccional?

Cada mensaje cuenta como un envío en el mismo medidor que sus campañas. La API está en el plan Volume, R$ 799 al mes con 400 mil envíos. Si agota la cuota, la API rechaza nuevos envíos hasta el próximo ciclo: no existe cobro por excedente.

Empiece por la prueba gratuita

Conozca el panel y autentique el dominio sin tarjeta. La API y la bandeja de pruebas vienen en el plan Volume.