Messagerie sortante & architecture du Delivery Center
Dans le Delivery Center (/delivery-center), vous pouvez gérer les envois transactionnels de passes, les campagnes promotionnelles segmentées, les modèles d'e-mails réutilisables, les listes de suppression de désinscription et les journaux de livraison en temps réel.
Passinstance orchestre les envois sortants à fort volume à l'aide de files de tâches en arrière-plan asynchrones connectées à son infrastructure e-mail gérée en UE (eu-central-1 Francfort), à la livraison SMS opérateur pour les SMS internationaux, ou à votre relais SMTP personnalisé chiffré :
Modèles d'e-mails & variables canoniques
Les modèles réutilisables créés dans Delivery Center -> Templates (Email Template Engine) garantissent une image de marque homogène pour vos notifications transactionnelles, messages de bienvenue et alertes de récupération de passe.
Syntaxe des variables & normalisation automatique
Passinstance impose une syntaxe à accolades simples : {placeholderName}. Si votre équipe créative saisit des doubles accolades de style Mustache ou Handlebars ({{passDownloadUrl}}), l'analyseur de Passinstance (normalizePlaceholders) les normalise automatiquement en accolades simples avant le stockage et le rendu.
| Jeton de variable | Type | Description technique & valeur rendue |
|---|---|---|
{passDownloadUrl} | Obligatoire | Lien de téléchargement intelligent canonique (passAccessUrl). Analyse le contexte de l'appareil destinataire pour diffuser le .pkpass Apple Wallet ou rediriger vers Google Wallet. |
{passUrl}, {passLink}, {smartLink} | Alias | Alias hérités reconnus et normalisés automatiquement vers {passDownloadUrl}. |
{appleWalletUrl} | Direct plateforme | Lien direct servant le bundle Apple Wallet .pkpass brut (application/vnd.apple.pkpass). |
{googleWalletUrl} | Direct plateforme | Lien direct d'enregistrement dans Google Wallet (https://pay.google.com/gp/v/save/<jwt>). |
{walletButtonText} | Chaîne localisée | Libellé de bouton localisé (par ex. « Ajouter à Wallet », « Zu Apple Wallet hinzufügen »). |
{firstName}, {lastName}, {name} | Contact | Nom du destinataire extrait des attributs client. |
{passFlowLink} | Inscription | Lien public d'inscription du PassFlow associé (/f/:url). |
{unsubscribeLink} | Conformité | Lien de désinscription en un clic signé par HMAC (GET /email/unsubscribe/:token). |
{attributeName} | Propriété personnalisée | Toute clé d'attribut personnalisé définie sur le modèle (par ex. {membershipNumber}, {tier}, {balance}). |
Conformité RFC 8058 pour la désinscription en un clic
Pour les envois marketing, Passinstance injecte automatiquement des en-têtes e-mail conformes à la norme RFC 8058 :
List-Unsubscribe: <https://api.passinstance.com/email/unsubscribe/{signedToken}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click
Cela active les boutons natifs « Se désinscrire » dans Gmail, Apple Mail et Yahoo Mail, limitant les signalements pour spam et protégeant la réputation de votre domaine.
Campagnes d'envoi par e-mail ou SMS : flux du Delivery Center
Pour lancer une campagne de distribution sortante par lot :
Étape 1 : filtrer votre audience
Dans Delivery Center -> New Campaign, sélectionnez votre modèle de passe et appliquez les filtres de segment :
-
Filtre de statut : cible les passes actifs (
status = 'ACTIVE'). -
Filtre non installés (
onlyUninstalled: true) : cible uniquement les clients qui n'ont pas encore ajouté leur passe sur un appareil (installedDevices === 0). -
Fenêtre de date de création : cible les passes créés sur une plage de dates précise.
Étape 2 : choisir le canal d'envoi
-
E-mail : acheminé via la livraison e-mail gérée ou votre relais SMTP personnalisé.
-
SMS : acheminé via la livraison SMS opérateur vers des numéros mobiles internationaux au format E.164.
Étape 3 : sélectionner ou rédiger votre message
Choisissez un modèle enregistré dans Delivery Center -> Templates ou rédigez un message ponctuel. Veillez à inclure {passDownloadUrl} dans le corps de l'e-mail.
Étape 4 : exécuter l'estimation préalable
Cliquez sur Estimer la portée (Estimate Reach, POST /api/v1/email-campaigns/estimate). Passinstance analyse votre audience :
-
Nombre total de passes correspondants.
-
Enregistrements d'e-mail/téléphone valides.
-
Contacts supprimés (désinscriptions et rejets permanents exclus).
-
Solde de crédits de messagerie requis.
Étape 5 : expédier ou planifier
Cliquez sur Démarrer l'envoi (Start Sendout, POST /api/v1/email-campaigns/:id/start) pour lancer immédiatement le traitement en arrière-plan via la file de tâches, ou définissez une date de publication ultérieure.
Tarification des envois, solde & rechargement de crédits
La livraison de messages sortants est facturée à l'usage en toute transparence :
| Canal | Tarif plateforme | Unité de facturation | Remarques |
|---|---|---|---|
| 0,0005 € EUR | Par e-mail livré | Inclut le routage SES, le suivi des rejets et le suivi d'ouverture | |
| SMS | 0,03 € EUR | Par segment GSM-7 de 160 car. | Routage opérateur mobile international pour la livraison SMS |
| Mises à jour push | 0,00 € (GRATUIT) | Pushs illimités | Les notifications push Apple APNs et Google Wallet sont toujours gratuites |
Suivre le solde & acheter des crédits :
-
Consulter le solde : consultez votre solde actuel dans Delivery Center ou via
GET /delivery/balance. -
Recharger les crédits : cliquez sur Ajouter du solde (Add Balance,
POST /delivery/top-up). Passinstance ouvre une session Stripe Checkout sécurisée vous permettant de créditer votre compte par carte bancaire, SEPA ou virement bancaire.
Envoi de passes individuels avec expédition directe par e-mail
Lors de l'émission manuelle d'un passe pour un client individuel :
-
1
Accédez à Passes -> Créer un passe individuel (Create Individual Pass).
-
2
Saisissez les attributs du client (
firstName,email, etc.). -
3
Cochez la case « Envoyer par e-mail » (Send by Email) dans la fenêtre d'émission.
-
4
Cliquez sur Créer le passe. Passinstance crée la fiche du passe et appelle immédiatement
POST /passes/:id/email/send, expédiant le lien de téléchargement intelligent personnalisé.
Vous pouvez également déclencher un e-mail pour un passe individuel à tout moment depuis sa vue détaillée en cliquant sur Actions rapides -> Envoyer par e-mail (POST /passes/:passId/send-email-with-template).
Routage SMTP personnalisé vérifié
Si votre espace de travail dispose d'un relais SMTP personnalisé configuré (AddonType.OWN_SMTP), tous les e-mails de passes individuels et toutes les campagnes d'envoi passent par votre propre serveur de messagerie au lieu de l'infrastructure SES par défaut de Passinstance.
Dépannage : pourquoi mon modèle d'e-mail ne s'envoie-t-il pas ?
Si un e-mail échoue lors de la création d'un passe, d'un envoi manuel ou d'une campagne, le blocage provient des contrôles d'exécution appliqués dans sendout-runtime.gates.ts :
1. Variable obligatoire {passDownloadUrl} manquante
Si un modèle est configuré comme exigeant une URL de passe (requiresPassUrl), mais que son contenu ne comporte pas {passDownloadUrl} (ni un alias accepté), le worker d'envoi interrompt l'opération avec une erreur BadRequestException. Correction : modifiez le modèle dans le Delivery Center et ajoutez {passDownloadUrl} dans le corps de l'e-mail.
2. Contrôle du moyen de paiement client (assertCustomerPaymentMethod)
Les envois automatisés exigent que les espaces de travail actifs disposent d'un moyen de paiement vérifié ou d'un solde de crédits positif. Si votre abonnement est en retard de paiement ou si votre solde est nul, la passerelle renvoie PaymentRequiredException. Correction : accédez à Paramètres -> Facturation -> Moyens de paiement pour mettre à jour votre carte ou recharger vos crédits.
3. Attributs de contact du destinataire manquants
Si la fiche du passe cible présente un champ email nul ou vide, le worker ignore le passe et consigne une erreur de validation. Correction : vérifiez que le passe contient une adresse e-mail valide et bien formatée.
4. Bascules d'envoi désactivées sur le modèle
Dans Paramètres du modèle -> Distribution & envois, vérifiez que le mode d'envoi concerné est activé :
-
adHocEmailEnabled === true(pour les envois manuels rapides). -
distributeOnCreate === true(pour l'expédition automatique à la génération du passe). -
downloadPageEmailEnabled === true(pour les demandes de transfert vers téléphone depuis un ordinateur).
5. Objet ou corps vide
Le contrôle préalable isManualPassEmailContentReady rejette les messages lorsque adHocEmailSubject ou adHocEmailTemplate est vide.
Coût d'envoi des SMS & configuration d'expéditeur personnalisé
Comprendre le coût par segment SMS
Les messages SMS sont facturés 0,03 € EUR par segment :
-
Encodage standard GSM-7 : jusqu'à 160 caractères par segment.
-
Encodage Unicode / UCS-2 (émojis, accents spéciaux) : jusqu'à 70 caractères par segment.
-
Messages multi-segments : les messages concaténés réservent 7 caractères par segment pour les en-têtes de concaténation (soit 153 caractères utiles en GSM-7, 67 en Unicode).
Conseil de pro : les notifications push Apple Wallet et Google Wallet sont 100 % gratuites et illimitées. Envoyez les passes initiaux par SMS ou e-mail, puis utilisez les notifications push (
changeMessage) pour les mises à jour ultérieures afin d'éliminer vos coûts de messagerie.
Configurer des identifiants d'expéditeur alphanumériques
Dans Paramètres -> Messagerie -> Paramètres SMS, vous pouvez définir le nom de votre entreprise comme identifiant d'expéditeur SMS (senderProfile.smsSenderName, jusqu'à 11 caractères alphanumériques) :
-
Europe, Royaume-Uni, Australie & majorité des marchés internationaux : les expéditeurs alphanumériques fonctionnent nativement sans pré-enregistrement. Les clients voient le nom de votre marque (par ex.
MYBRAND) comme expéditeur. -
États-Unis & Canada : les opérateurs télécoms interdisent strictement les expéditeurs alphanumériques non enregistrés. Les messages vers les États-Unis et le Canada sont acheminés via des numéros mutualisés conformes 10DLC ou des numéros courts dédiés.
Pourquoi Passinstance ne joint-il pas directement les fichiers .pkpass aux e-mails ?
Les commerçants demandent souvent pourquoi les e-mails Passinstance contiennent un lien intelligent ({passDownloadUrl}) au lieu de joindre directement le fichier .pkpass brut à l'e-mail. Trois raisons techniques majeures l'expliquent :
1. Incompatibilité des clients e-mail Android (corruption MIME)
Les applications de messagerie mobiles sur Android (y compris les applications officielles Gmail et Outlook) ne reconnaissent pas le type MIME Apple Wallet application/vnd.apple.pkpass. Lorsqu'un utilisateur Android appuie sur une pièce jointe .pkpass, le client e-mail la traite comme une archive .zip brute et affiche un contenu binaire illisible ou un message d'erreur du type « Impossible d'ouvrir le fichier ».
2. L'architecture Google Wallet exige des liens JWT cloud
Contrairement à Apple Wallet, Google Wallet ne peut pas importer de fichiers locaux. Google Wallet requiert une URL cloud authentifiée d'ajout au portefeuille (https://pay.google.com/gp/v/save/<signed_jwt>). Grâce aux liens intelligents, les utilisateurs Android sont automatiquement redirigés vers Google Wallet sans friction.
3. Sécurité mono-appareil & télémétrie d'installation
Un fichier .pkpass brut joint à un e-mail peut être transféré à des centaines de destinataires non autorisés. Avec les liens de téléchargement intelligents :
-
Vous pouvez imposer le verrouillage mono-appareil (
limitToOneActivePerPass). -
Vous pouvez activer la protection par code PIN et des dates d'expiration de téléchargement (
enableDownloadUntil). -
Vous capturez une télémétrie d'appareil complète (système d'exploitation, navigateur, horodatage d'installation, attribution UTM) au moment où le passe est réclamé.
Référence de l'API REST d'envoi
| Méthode | Chemin de l'endpoint | Portée d'authentification | Description |
|---|---|---|---|
| POST | /api/v1/passes/:id/send-email | Clé API (passes) | Expédie un e-mail transactionnel pour un passe unique avec le modèle par défaut. |
| POST | /api/v1/passes/:passId/send-email-with-template | Clé API (passes) | Envoie l'e-mail d'un passe unique avec un templateId et une idempotencyKey spécifiques. |
| POST | /api/v1/passes/:passId/send-sms | Clé API (passes) | Envoie un SMS pour un passe unique au phoneNumber destinataire. |
| POST | /api/v1/email-campaigns | Clé API (delivery) | Crée un brouillon de campagne d'envoi par lot. |
| POST | /api/v1/email-campaigns/estimate | Clé API (delivery) | Retourne la taille de l'audience, le nombre de passes livrables et le crédit nécessaire. |
| POST | /api/v1/email-campaigns/:id/start | Clé API (delivery) | Met la campagne en file pour exécution immédiate en arrière-plan. |
| GET | /delivery/balance | Clé API (billing) | Retourne le solde prépayé de messagerie actuel et la devise. |
| POST | /delivery/top-up | Clé API (billing) | Crée une session Stripe Checkout pour acheter des crédits de messagerie. |
| GET | /email-campaigns/track/:id/open | Public | Pixel de suivi transparent enregistrant l'horodatage d'ouverture des e-mails. |
Documentation connexe
-
Distribution en libre-service — PassFlows, liens intelligents, codes QR et tags NFC.
-
Liens de téléchargement & PassFlow — Routage des liens intelligents, protection par PIN et localisation PassFlow.
-
Votre propre adresse d'expéditeur & SMTP personnalisé — Guide complet de configuration des relais SMTP personnalisés.
-
Marque blanche & personnalisation avancée — Domaines personnalisés et habillage du portail.
