Arquitectura de mensajería saliente y Delivery Center
En Delivery Center (/delivery-center), puede gestionar envíos transaccionales de pases, campañas promocionales segmentadas, plantillas de correo electrónico reutilizables, listas de supresión por baja y registros de entrega en tiempo real.
Passinstance orquesta la mensajería saliente de gran volumen a través de colas asíncronas de trabajos en segundo plano conectadas a la infraestructura gestionada de correo en la UE (eu-central-1 Fráncfort), la entrega SMS a través de operadores para SMS globales o su retransmisor SMTP personalizado cifrado:
Plantillas de correo electrónico y marcadores canónicos
Las plantillas reutilizables creadas en Delivery Center -> Plantillas (Email Template Engine) garantizan una coherencia de marca uniforme en notificaciones transaccionales, mensajes de bienvenida y alertas de recuperación de pases.
Sintaxis de marcadores y normalización automática
Passinstance aplica una sintaxis de llaves simples: {placeholderName}. Si su equipo de diseño introduce llaves dobles al estilo Mustache o Handlebars ({{passDownloadUrl}}), el analizador de Passinstance (normalizePlaceholders) las normaliza automáticamente a llaves simples antes del almacenamiento y el renderizado.
| Token de marcador | Tipo | Descripción técnica y valor renderizado |
|---|---|---|
{passDownloadUrl} | Obligatorio | El enlace inteligente canónico de descarga (passAccessUrl). Inspecciona el contexto del dispositivo destinatario para servir el .pkpass de Apple Wallet o redirigir a Google Wallet. |
{passUrl}, {passLink}, {smartLink} | Alias | Alias heredados reconocidos que se normalizan automáticamente a {passDownloadUrl}. |
{appleWalletUrl} | Directo por plataforma | Enlace directo que sirve el paquete .pkpass sin procesar de Apple Wallet (application/vnd.apple.pkpass). |
{googleWalletUrl} | Directo por plataforma | Enlace directo de guardado en Google Wallet (https://pay.google.com/gp/v/save/<jwt>). |
{walletButtonText} | Cadena localizada | Etiqueta localizada del botón (por ejemplo, "Añadir a Wallet", "Zu Apple Wallet hinzufügen"). |
{firstName}, {lastName}, {name} | Contacto | Nombre del destinatario extraído de los atributos del cliente. |
{passFlowLink} | Registro | Enlace público de inscripción del PassFlow asociado (/f/:url). |
{unsubscribeLink} | Cumplimiento | Enlace de baja en un clic firmado con HMAC (GET /email/unsubscribe/:token). |
{attributeName} | Propiedad personalizada | Cualquier clave de atributo personalizado definida en la plantilla (por ejemplo, {membershipNumber}, {tier}, {balance}). |
Cumplimiento de baja en un clic según RFC 8058
En los envíos promocionales, Passinstance inyecta automáticamente cabeceras de correo conformes con RFC 8058:
List-Unsubscribe: <https://api.passinstance.com/email/unsubscribe/{signedToken}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Esto habilita los botones nativos de "Anular suscripción" en Gmail, Apple Mail y Yahoo Mail, reduciendo las denuncias por spam y protegiendo la reputación de su dominio.
Envíos por correo electrónico o SMS: flujo de trabajo en Delivery Center
Para lanzar una campaña de distribución masiva saliente:
Paso 1: filtre su audiencia
En Delivery Center -> Nueva campaña, seleccione su plantilla de pase y aplique filtros de segmento:
-
Filtro de estado: Diríjase a pases activos (
status = 'ACTIVE'). -
Filtro de no instalados (
onlyUninstalled: true): Diríjase únicamente a los clientes que aún no han añadido el pase a ningún dispositivo (installedDevices === 0). -
Ventana de fecha de creación: Segmente pases creados en un intervalo de fechas concreto.
Paso 2: elija el canal de entrega
-
Correo electrónico: Entregado a través de la infraestructura gestionada de correo o su retransmisor SMTP personalizado.
-
SMS: Entregado mediante envío SMS por operadores a números móviles internacionales en formato E.164.
Paso 3: seleccione o redacte el mensaje
Elija una plantilla guardada en Delivery Center -> Plantillas o redacte un mensaje puntual. Asegúrese de incluir {passDownloadUrl} en el cuerpo del correo.
Paso 4: ejecute la estimación previa
Haga clic en Estimar alcance (POST /api/v1/email-campaigns/estimate). Passinstance analiza la audiencia y muestra:
-
Total de pases coincidentes.
-
Registros válidos de correo electrónico o teléfono.
-
Contactos suprimidos (bajas y rebotes duros excluidos).
-
Saldo de créditos de mensajería requerido.
Paso 5: envíe o programe
Haga clic en Iniciar envío (POST /api/v1/email-campaigns/:id/start) para comenzar el procesamiento inmediato en segundo plano mediante la cola de trabajos, o establezca una fecha futura de publicación.
Precios de entrega, saldo y recarga de créditos
La entrega de mensajes salientes se factura con un modelo transparente de pago por uso:
| Canal | Tarifa de la plataforma | Unidad de facturación | Notas |
|---|---|---|---|
| Correo electrónico | €0.0005 EUR | Por correo entregado | Incluye enrutamiento SES, supervisión de rebotes y seguimiento de aperturas |
| SMS | €0.03 EUR | Por segmento GSM-7 de 160 caracteres | Enrutamiento global de operadores móviles para entrega SMS |
| Actualizaciones push | €0.00 (GRATIS) | Envíos push ilimitados | Las notificaciones push de Apple APNs y Google Wallet son siempre gratuitas |
Supervisión del saldo y compra de créditos:
-
Consultar saldo: Visualice su saldo actual en Delivery Center o mediante
GET /delivery/balance. -
Recargar créditos: Haga clic en Añadir saldo (
POST /delivery/top-up). Passinstance abre una sesión segura de Stripe Checkout que le permite recargar su cuenta con tarjeta de crédito, SEPA o transferencia bancaria.
Envío de pases individuales con entrega directa por correo
Cuando emita manualmente un pase a un cliente concreto:
-
1
Vaya a Pases -> Crear pase individual.
-
2
Introduzca los atributos del cliente (
firstName,email, etc.). -
3
Marque la casilla "Enviar por correo electrónico" en el modal de emisión.
-
4
Haga clic en Crear pase. Passinstance crea el registro del pase e invoca inmediatamente
POST /passes/:id/email/send, enviando el enlace inteligente personalizado de descarga.
También puede enviar un correo electrónico para un pase concreto en cualquier momento desde la vista de detalle del pase haciendo clic en Acciones rápidas -> Enviar por correo electrónico (POST /passes/:passId/send-email-with-template).
Enrutamiento verificado por SMTP personalizado
Si su espacio de trabajo tiene configurado un retransmisor SMTP personalizado (AddonType.OWN_SMTP), todos los correos electrónicos de pases individuales y los envíos de campañas se enrutan a través de su propio servidor de correo en lugar de la infraestructura SES predeterminada de Passinstance.
Resolución de problemas: plantilla de correo que no se envía (¿por qué no se envía mi plantilla de correo?)
Si un correo electrónico no se envía durante la creación del pase, el envío manual o la ejecución de una campaña, el fallo se debe a los controles en tiempo de ejecución aplicados en sendout-runtime.gates.ts:
1. Falta el marcador obligatorio {passDownloadUrl}
Si una plantilla está marcada como que requiere una URL de pase (requiresPassUrl), pero su contenido no incluye {passDownloadUrl} (ni un alias admitido), el worker de despacho se detiene con BadRequestException. Solución: Edite la plantilla en Delivery Center y añada {passDownloadUrl} al cuerpo del correo.
2. Control de método de pago del cliente (assertCustomerPaymentMethod)
Los envíos automatizados requieren que los espacios de trabajo activos dispongan de un método de pago verificado registrado o de un saldo positivo de créditos. Si su suscripción presenta un pago vencido o su saldo es cero, la pasarela lanza PaymentRequiredException. Solución: Vaya a Configuración -> Facturación -> Métodos de pago y actualice su tarjeta o recargue créditos.
3. Faltan atributos de contacto del destinatario
Si el registro del pase objetivo tiene un campo email nulo o vacío, el worker omite ese pase y registra un error de validación. Solución: Verifique que el registro del pase contenga una dirección de correo electrónico válida y bien formada.
4. Interruptores de envío desactivados en la plantilla
En Configuración de la plantilla -> Distribución y envíos, compruebe que el modo de envío correspondiente esté habilitado:
-
adHocEmailEnabled === true(para envíos rápidos manuales). -
distributeOnCreate === true(para el despacho automatizado al generar el pase). -
downloadPageEmailEnabled === true(para solicitudes de reenvío al móvil desde escritorio).
5. Línea de asunto o cuerpo vacíos
El control previo isManualPassEmailContentReady rechaza los mensajes en los que adHocEmailSubject o adHocEmailTemplate están en blanco.
Costes de envío de SMS y configuración de remitente personalizado
Cómo funcionan los costes por segmento SMS
Los mensajes SMS se facturan a €0.03 EUR por segmento:
-
Codificación estándar GSM-7: Hasta 160 caracteres por segmento.
-
Codificación Unicode / UCS-2 (emojis, acentos especiales): Hasta 70 caracteres por segmento.
-
Mensajes multisegmento: Los mensajes concatenados reservan 7 caracteres por segmento para las cabeceras de concatenación (153 caracteres en GSM-7, 67 en Unicode).
Consejo práctico: Las notificaciones push de Apple Wallet y Google Wallet son 100 % gratuitas e ilimitadas. Envíe los pases iniciales por SMS o correo electrónico y utilice notificaciones push (
changeMessage) para las actualizaciones posteriores para eliminar costes de mensajería.
Configuración de identificadores de remitente alfanuméricos
En Configuración -> Mensajería -> Configuración de SMS, puede configurar el nombre de su empresa como identificador de remitente SMS (senderProfile.smsSenderName, hasta 11 caracteres alfanuméricos):
-
Europa, Reino Unido, Australia y la mayoría de mercados internacionales: Los remitentes alfanuméricos funcionan de forma inmediata sin registro previo. Los clientes ven el nombre de su empresa (por ejemplo,
MYBRAND) como remitente. -
Estados Unidos y Canadá: Los operadores de telecomunicaciones prohíben estrictamente los remitentes alfanuméricos sin registro. Los mensajes hacia EE. UU. y Canadá se entregan mediante números compartidos conformes con 10DLC o códigos cortos dedicados.
Por qué Passinstance no adjunta archivos .pkpass directamente en los correos electrónicos
Los comercios suelen preguntar por qué los correos de Passinstance contienen un enlace inteligente ({passDownloadUrl}) en lugar de adjuntar directamente el archivo .pkpass sin procesar. Existen tres motivos técnicos fundamentales:
1. Incompatibilidad en clientes de correo de Android (corrupción de MIME)
Los clientes de correo móvil en Android (incluidas las aplicaciones oficiales de Gmail y Outlook) no reconocen el tipo MIME de Apple Wallet application/vnd.apple.pkpass. Cuando un usuario de Android pulsa un archivo .pkpass adjunto, el cliente de correo lo trata como un archivo .zip sin procesar, mostrando contenido binario ilegible o el error "No se puede abrir el archivo".
2. La arquitectura de Google Wallet exige enlaces JWT en la nube
A diferencia de Apple Wallet, Google Wallet no puede importar archivos locales. Google Wallet requiere una URL autenticada en la nube para añadir al monedero (https://pay.google.com/gp/v/save/<signed_jwt>). Al emplear enlaces inteligentes, los usuarios de Android son redirigidos automáticamente a Google Wallet sin fricción.
3. Seguridad de dispositivo único y telemetría de dispositivos
Un archivo .pkpass adjunto en un correo puede reenviarse a cientos de destinatarios no autorizados. Con enlaces inteligentes de descarga:
-
Puede aplicar la vinculación a un único dispositivo (
limitToOneActivePerPass). -
Puede exigir protección mediante PIN y fechas límite de descarga (
enableDownloadUntil). -
Captura la telemetría completa del dispositivo (sistema operativo, navegador, fecha y hora de instalación, atribución UTM) cuando se reclama el pase.
Referencia de la API REST de entrega
| Método | Ruta del endpoint | Ámbito de autenticación | Descripción |
|---|---|---|---|
| POST | /api/v1/passes/:id/send-email | Clave API (passes) | Envía el correo transaccional de un pase individual utilizando la plantilla predeterminada. |
| POST | /api/v1/passes/:passId/send-email-with-template | Clave API (passes) | Envía el correo de un pase individual con un templateId específico y idempotencyKey. |
| POST | /api/v1/passes/:passId/send-sms | Clave API (passes) | Envía un SMS de pase individual al phoneNumber del destinatario. |
| POST | /api/v1/email-campaigns | Clave API (delivery) | Crea un borrador de campaña de envío por lotes. |
| POST | /api/v1/email-campaigns/estimate | Clave API (delivery) | Devuelve el tamaño de audiencia, el recuento de pases entregables y los créditos necesarios. |
| POST | /api/v1/email-campaigns/:id/start | Clave API (delivery) | Encola la campaña para su ejecución inmediata en segundo plano. |
| GET | /delivery/balance | Clave API (billing) | Devuelve el saldo prepago de mensajería actual y su divisa. |
| POST | /delivery/top-up | Clave API (billing) | Crea una sesión de Stripe Checkout para adquirir créditos de mensajería. |
| GET | /email-campaigns/track/:id/open | Público | Píxel transparente de seguimiento que registra las marcas temporales de apertura de correo. |
Documentación relacionada
-
Distribución en autoservicio — PassFlows, enlaces inteligentes, códigos QR y etiquetas NFC.
-
Enlaces de descarga y PassFlow — Enrutamiento de enlaces inteligentes, protección con PIN y localización de PassFlow.
-
Su propia dirección de remitente y SMTP personalizado — Guía completa para configurar retransmisores SMTP personalizados.
-
Marca personalizada y opciones de marca blanca — Dominios propios y personalización visual del portal.
