Campañas de correo electrónico

Una campaña de correo electrónico envía una versión publicada de content a una audiencia consentida desde su propio dominio verificado.

Lo que necesitas antes de la primera campaña

Dos cosas: un plan que incluya el canal de correo electrónico y un dominio de envío verificado. Compruébalos en ese orden.

Un plan con el canal de correo electrónico

Email pertenece al generador de bots y la línea de creadores de bots tiene cuatro planes:

• Start es gratuito y no incluye correo electrónico;
• Pro, Business y Enterprise son pagos y cada uno lo incluye.

Los nombres son lo que hace tropezar a la gente: el plan gratuito se llama Start y el de pago más barato se llama Pro.

Ningún plan de Customer Engagement otorga correo electrónico, ni comunicación, ni soporte, ni marketing, ni experto en marketing. La línea de pedido "Campañas" en los dos últimos significa mensajes proactivos y ventanas emergentes en el widget, no correo. La asignación gratuita para el creador de bots que viene con un plan CE pago tampoco tiene correo electrónico, porque esa asignación es el plan Start.

En un plan sin canal de correo electrónico toda la superficie del correo electrónico está cerrada: dominios de envío, rutas entrantes, campañas y sus estadísticas. Cada solicitud que se les envía responde 402 y nombra la capacidad que falta (email). Verifique el plan antes de editar DNS: sin el canal de correo electrónico no puede agregar el dominio de envío, por lo que configurar SPF, DKIM y DMARC sería un trabajo en vano. Ver Planes.

Un dominio de envío verificado

Mientras el dominio no está verificado no se envía nada. El correo electrónico de su propio dominio explica cómo configurar uno.

Una vez que ambos estén implementados, abra la sección Correo electrónico y siga el enlace Campañas de correo electrónico.

El editor

El editor de campañas tiene cuatro pasos.

Mensaje y remitente. Nombre de la campaña (hasta 160 caracteres), dominio de envío, nombre del remitente, dirección de respuesta, asunto (hasta 255 caracteres) y preencabezado (hasta 500 caracteres). La respuesta debe ser una dirección simple como hello@example.com, sin un nombre para mostrar. Los retornos de carro y los avances de línea se rechazan en el nombre del remitente, la respuesta, el asunto y el preencabezado, porque permitirían la inyección de encabezado.

Contenido y vista previa. Elija una versión de contenido de correo electrónico publicado o cree una a partir de una plantilla. La campaña almacena la identificación del documento junto con el número de versión exacto, por lo que volver a publicar el documento más tarde no cambia una campaña que ya está programada.

Público y experimento. Todos los suscriptores de correo electrónico del bot o uno listo segment. Opcionalmente, vincule un experimento A/B; Luego, la campaña captura la versión del experimento cuando está programada y genera informes en función de esa instantánea.

Horario y privacidad. Hora de envío, modo de zona horaria, correos electrónicos por minuto (1 a 10 000) y el interruptor de seguimiento abierto. La hora de envío es opcional: lanzar una campaña sin ella se inicia inmediatamente.

Hay dos modos de zona horaria. En la zona horaria de la campaña, todos reciben el mensaje en un único momento absoluto, calculado en la propia zona horaria de la campaña. En la hora local del destinatario, todos ven la misma hora del reloj de pared en su propia zona.

La lista de zonas horarias es un conjunto fijo de zonas comunes (Moscú, Belgrado, Londres, Berlín, Dubai, Almaty, Tbilisi, Ereván, Tashkent, Bangkok, Tokio, Nueva York, Los Ángeles, UTC).

El horario de verano se maneja explícitamente:

• el editor rechaza una hora de envío que no existe en la zona horaria de la campaña en esa fecha y lo dice debajo del campo;
• en el modo de destinatario, un destinatario cuya hora local no existe ese día es reportado como nonexistent_local_time por la verificación del destinatario, lo que bloquea el lanzamiento hasta que elija otra hora;
• cuando un tiempo de pared ocurre dos veces, se usa el instante anterior, de manera consistente para todos.

En el modo de destinatario, se suprime a una persona sin una zona horaria utilizable, por lo que nadie recibe correo a una hora arbitraria.

Verifique el destinatario antes de enviar

Verifique los destinatarios nunca envía nada. Construye la audiencia según el borrador actual y las reglas de consentimiento y responde con el número que recibiría la campaña, el número suprimido y por qué, además de errores de contenido y advertencias. La respuesta utiliza códigos sin formato, los mismos que verás en la interfaz.

Una dirección se cuenta como suprimida cuando:

• su suscripción no es subscribed, y el motivo es entonces el estado de la suscripción misma: unsubscribed, bounced o complained;
• la dirección está vacía o inutilizable (invalid_email);
• la misma dirección normalizada ya aparece en esta campaña (duplicate); El modo local del destinatario
• está activado y la persona no tiene zona horaria (missing_timezone), una no reconocida (invalid_timezone) o una hora de envío local que no existe ese día (nonexistent_local_time); El consentimiento
• fue revocado entre la materialización y el intento de envío (no_consent).

Los errores son los que realmente bloquean el inicio:

• domain_not_verified: el dominio de envío no está verificado;
• content_not_published: la versión del contenido seleccionado falta o no está publicada;
• audience_not_ready: el segmento elegido no existe o no ha terminado de computarse;
• experiment_not_ready: el experimento vinculado no se está ejecutando o su versión actual no es asignada por el suscriptor;
• scheduled_in_past: el tiempo de envío ya pasó;
• nonexistent_local_time: ver arriba;
• empty_audience: nadie recibiría la campaña;
• todos los errores de contenido enumerados en Content studio, informados contra content_document_id y el bloque infractor.

También aparecen advertencias de contenido, además de una que la propia verificación de la campaña agrega:

• missing_plain_text: el contenido no tiene ningún texto legible, solo medios o botones, por lo que la parte de texto sin formato del mensaje estaría vacía.

La campaña está lista para lanzarse solo cuando no hay errores. Las advertencias nunca lo bloquean.

Enviar correo electrónico de prueba entrega el contenido propio de la campaña a una identidad de correo electrónico ya verificada y que aún acepta la identidad de este bot. Nunca toca las filas de destinatarios de la campaña y nunca acepta una dirección escrita, por lo que no puede consumir ni corromper un envío programado.

Lanzamiento y control

Una campaña solo se puede lanzar desde Borrador. El lanzamiento solicita una confirmación explícita y la revisión que tienes en pantalla. En ese momento, la campaña se materializa: la versión del contenido, el remitente, la audiencia, la programación y la versión del experimento se congelan en una instantánea de envío inmutable y se crea una fila de destinatarios por dirección elegible.

Después de eso, la campaña ya no se puede editar. Para cambiar algo, use Crear copia e inicie la copia. Los estados de

son Borrador, Programado, Enviando, En pausa, Completado, Cancelado, Fallido y Archivado. Acciones de control y dónde están permitidas:

• Pausa: desde Programado o Enviando.
• Reanudar: desde En pausa, vuelve a Programado.
• Cancelar: desde Borrador, Programado, Enviando o Pausado. A los destinatarios a los que no se les ha enviado no se les envía posteriormente.
• Archivo: desde borrador, completado, cancelado o fallido.

Cada acción de control lleva también la revisión esperada, por lo que dos operadores no pueden pelear por la misma campaña sin que uno de ellos sea informado.

El envío en sí se rige por el valor de correos electrónicos por minuto, se ejecuta en lotes arrendados y es resistente a un reinicio del trabajador. Un destinatario cuyo envío falla temporalmente se reintenta con un retraso creciente que comienza en 15 segundos y tiene un límite de 15 minutos. Un envío que se entregó al proveedor pero cuyo resultado nunca se confirmó se registra como Entrega desconocida. No se vuelve a intentar porque se correría el riesgo de enviar un segundo mensaje a la misma persona.

Seguimiento, privacidad y cancelaciones de suscripción

Cada URL rastreada (abra píxel, haga clic en redirigir y cancele la suscripción por igual) es un token firmado en su propia instalación, en el formato https://<your-host>/e/t/<token>. Los tokens están firmados por HMAC, están destinados a un bot, una campaña y un destinatario, y caducan 90 días después del envío. La clave de firma se deriva del secreto del webhook de correo electrónico de la instalación y, sin ese secreto, las campañas se niegan a enviarse, por lo que los enlaces sin seguimiento nunca se envían.

• El seguimiento abierto es un GIF de 1×1 y es opcional. Desactivar "Recopilar estadísticas abiertas" simplemente lo omite, y las métricas de entrega, clics, quejas y cancelaciones de suscripción siguen funcionando. Los recuentos abiertos son siempre un límite inferior; la explicación está en Correo electrónico de tu propio dominio.
• El seguimiento de clics reescribe únicamente los botones de enlace https://. Un token de clic lleva el destino, y el destino en sí debe ser una URL https:// con un host y sin credenciales integradas, por lo que la redirección no puede apuntar a ningún otro lugar.
• Los tokens para cancelar la suscripción no contienen ningún ID de enlace ni destino: dichos tokens pueden excluir a alguien, pero no pueden redirigir a ninguna parte.

Un token no válido, caducado, de inquilinos cruzados o desconocido responde a 404 sin más detalles, por lo que no se puede utilizar un token para buscar campañas o destinatarios válidos.

Cancelar la suscripción sigue RFC 8058 con un solo clic. Un GET muestra una página de confirmación HTML simple sin JavaScript; lo realiza un POST con el campo de formulario único List-Unsubscribe=One-Click. Reproducir la misma cancelación de suscripción se considera un éxito, porque los clientes de correo buscan previamente los enlaces y la gente hace clic dos veces. La exclusión voluntaria se registra en la fila del destinatario y como efecto de consentimiento canónico en la misma transacción, por lo que el enlace nunca puede informar que se haya realizado correctamente mientras el consentimiento permanezca suscrito. Informe

El informe de la campaña separa: Destinatarios, Suprimidas, En espera, Enviando, Aceptadas por el proveedor, Entrega desconocida, Entregadas, Abiertas, Clics, Rebotadas, Quejas, Canceladas, Fallidas y Canceladas. Los enlaces en los que se hace clic se informan por enlace y los destinatarios se pueden enumerar página por página con su estado y motivo de supresión.

Los ingresos atribuidos se informan por modelo de atribución y por moneda, y nunca se suman entre ellos: diferentes modelos atribuyen legítimamente la misma conversión de manera diferente, y un total de monedas mixtas no tendría sentido.

Respuestas de los destinatarios

Una ruta entrante convierte una dirección en un dominio verificado en una conversación de soporte. La parte local se almacena sólo como un hash irreversible, por lo que la dirección en sí nunca se guarda junto a la ruta.

Las rutas aún no tienen pantalla en el panel. Administrelos a través de la API con un token que lleva settings:read / settings:write:

curl -X POST "$BASE_URL/api/bots/$BOT_ID/email/inbound-routes" \
  -H "Authorization: Bearer $PAT" -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com","local_part":"support"}'

La parte local está en minúsculas y debe coincidir con [a-z0-9][a-z0-9._+-]{0,62}. El dominio ya debe estar verificado para este bot; de lo contrario, la llamada responde 422; la misma dirección responde dos veces 409. La respuesta repite la dirección completa una vez, en el momento de la creación, y luego la lista muestra solo el dominio, porque la parte local no se almacena. Una instalación sin secreto de webhook de correo electrónico configurado responde a 503, y el correo entrante está completamente desactivado.

El correo entrante se normaliza antes de que pueda tocar un cuadro de diálogo:

• el remitente se dirige a un suscriptor mediante la dirección normalizada;
• In-Reply-To y References se utilizan para continuar el hilo existente, pero sólo cuando el hilo pertenece a la misma persona; La historia citada por
• es despojada del cuerpo;
• el mensaje sin formato tiene un límite de 8 MiB, el texto extraído de 256 KiB, el asunto de 255 caracteres y References de 32 entradas;
• se guardan como máximo 5 archivos adjuntos de como máximo 1 MiB cada uno, almacenados bajo una clave dirigida al contenido; los archivos adjuntos ejecutables (.bat, .cmd, .com, .dll, .exe, .msi, .scr y tipos MIME ejecutables de MS-DOS) se rechazan;
• un mensaje solo HTML se reduce a texto.

Un mensaje dirigido a una ruta desconocida se rechaza con 404. Eso tiene un costo que vale la pena conocer de antemano: el proveedor lee 404 como una entrega fallida, por lo que lo volverá a intentar durante horas y luego le informará del error. Una dirección mal escrita o una ruta que no existe significa horas de reintentos del proveedor.

La razón radica en cómo se almacenan las rutas. La parte local de una ruta se mantiene como un hash calculado con el secreto del webhook de correo electrónico de la instalación, y esos hashes no se pueden volver a ingresar, por lo que después de rotar el secreto ya no se puede encontrar ninguna ruta. Responder "aceptado" le indicaría al proveedor que el correo fue entregado, y el correo entrante desaparecería silenciosamente: nada volvería a intentarlo y nadie se enteraría. Una negativa hace visible la rotura.

Consecuencia práctica: si ve reintentos del proveedor y quejas sobre el correo entrante después de rotar el secreto del webhook de correo electrónico, vuelva a crear las rutas entrantes, porque las antiguas ya no pueden coincidir.

Contrato de proveedor

Si opera su propia instalación o escribe un adaptador para un proveedor de servicios de correo electrónico, estos son los dos puntos finales públicos con los que habla el proveedor. Ambos se autentican con una firma HMAC-SHA256 sobre el cuerpo de la solicitud sin formato, codificado en hexadecimal, en el encabezado X-Signature, utilizando el secreto del webhook de correo electrónico configurado. Una solicitud sin firma se rechaza con 401, al igual que cualquier solicitud cuando no se configura ningún secreto: el punto final falla al cerrarse.

Eventos de entrega y participación

POST /esp/{provider}/webhook, cuerpo limitado a 1 MiB:

{
  "provider_id": "prv_00000000-0000-0000-0000-000000000000",
  "event": "delivered",
  "bounce_class": "hard",
  "url": "https://example.com/offer",
  "event_id": "evt_0000000001",
  "tag": "email-campaign:11111111-1111-1111-1111-111111111111:22222222-2222-2222-2222-222222222222"
}

Este es el contrato genérico de la plataforma, no la forma nativa de ningún proveedor. Su adaptador traduce la devolución de llamada del proveedor.

• event es uno de delivered, opened, clicked, bounced, complained, unsubscribed. Un valor no reconocido se almacena para inspección y no cambia su estado.
• bounce_class es hard o soft, y solo tiene sentido para bounced.
• tag son los metadatos estables proporcionados en el momento del envío, en el formato email-campaign:<campaign-id>:<subscriber-id>. Permite que una devolución de llamada que llega antes de que se haya persistido la identificación del proveedor aún encuentre a su destinatario.

Asignación de evento a estado:

• delivered: el mensaje y el destinatario de la campaña se entregan;
• bounced con bounce_class: hard: mensaje rebotado, dirección suprimida, destinatario rebotado;
• bounced con bounce_class: soft: solo grabado. Un rebote suave dice algo sobre este intento, no sobre la dirección, por lo que nunca suprime ni mueve al destinatario;
• complained: denuncia registrada, dirección cerrada permanentemente;
• unsubscribed: consentimiento revocado, destinatario cancelado;
• opened y clicked: registrados como eventos, sin transición de estado.

Una devolución de llamada fuera de servicio nunca puede hacer retroceder un estado terminal.

La idempotencia utiliza event_id cuando el proveedor envía uno y, en caso contrario, un SHA-256 del cuerpo sin formato. El cheque, los efectos y el recibo se escriben en una sola transacción, serializada por bot y clave, por lo que no pueden aplicarse dos entregas simultáneas del mismo evento.

Los códigos de respuesta le indican a su adaptador qué hacer:

• 200: entendido. Esto incluye eventos que se ignoraron deliberadamente, como un duplicado o un mensaje de identificación que esta instalación nunca envió: volver a intentarlo no cambiará el resultado.
• 400: cuerpo mal formado o falta provider_id/event.
• 401: firma mala o ausente.
• 413: cuerpo por encima del límite.
• 500: un fallo transitorio de nuestra parte. Esta es la única clase que debes volver a intentar.

Correo electrónico entrante

POST /esp/{provider}/inbound, cuerpo limitado a 12 MiB:

{
  "event_id": "in_0000000001",
  "raw_mime": "<base64 of the original MIME message>"
}

El MIME decodificado no debe exceder los 8 MiB. Las respuestas son:

• 200 con {"created": true|false}: el mensaje fue aceptado; false significa un duplicado de un event_id ya grabado.
• 404: la dirección del destinatario no coincide con ninguna ruta. Volver a intentarlo vale la pena: la ruta puede aparecer y perder silenciosamente el correo entrante es peor que reintentos adicionales. Consulte "Un mensaje dirigido a una ruta desconocida" más arriba.
• 400: no se pudo analizar el sobre o MIME.
• 401: la firma falló.
• 413: el cuerpo de la solicitud tenía más de 12 MiB.

Ninguno de los puntos finales devuelve credenciales de proveedor, direcciones de destinatarios que no estaban en la solicitud o la parte local de una ruta entrante. Fallos de seguimiento y cancelación de suscripción responden a 404 sin decir qué verificación falló.

Solución de problemas

1. Cualquier pantalla de correo electrónico o solicitud responde 402: su plan no incluye la capacidad email. Esto no es una mala configuración, y los dominios de envío, las rutas entrantes, las campañas y sus estadísticas permanecen cerradas hasta que el plan sea Pro, Business o Enterprise. Los registros DNS no tienen nada que ver con eso.
2. No se envía nada y la tarjeta de dominio muestra una advertencia: el dominio de envío aún no está verificado. Consulte Correo electrónico desde su propio dominio.
3. "La campaña aún no se puede iniciar": abra la verificación del destinatario y corrija todos los errores; Las advertencias por sí solas nunca bloquean un lanzamiento.
4. Muchos destinatarios suprimidos como missing_timezone: la campaña está en modo local de destinatario pero su gente no tiene zona horaria. Cambie a la zona horaria de la campaña o complete el campo de perfil.
5. La hora de envío se rechaza o la verificación informa nonexistent_local_time: esa hora del reloj no existe en esa fecha debido a un salto del horario de verano. Elige otro momento.
6. Las aperturas parecen demasiado bajas: esperadas y no reparables. En su lugar, compare las campañas por clics.
7. Los eventos del proveedor nunca llegan: verifique que el adaptador firme el cuerpo sin formato exacto y que el secreto del webhook coincida; una devolución de llamada sin firmar se responde con 401.
8. El proveedor se queja de entregas entrantes repetidas: la dirección en la que se escribe no coincide con ninguna ruta. Verifique la lista de rutas y, si el secreto del webhook de correo electrónico se rotó recientemente, vuelva a crear las rutas.

¿Qué sigue?

• Estudio de contenido: redacción y publicación del contenido del correo electrónico.
• Correo electrónico de tu propio dominio: DKIM, SPF, DMARC, bajas y rebotes.
• Transmisiones: envío de un documento de contenido a Telegram, VK, WhatsApp, chat web o correo electrónico.
• Experimentos y atribución: experimentos A/B e ingresos atribuidos.