Skip to content
Guide du centre d'aide · Distribution des passesPhase d'intégration 5
10 min de lectureVérifié 2026-11-16

Envoi par e-mail & SMS

Utilisez le Centre d'envoi, les modèles d'e-mails, le suivi des rebonds SES et votre propre serveur d'envoi SMTP.

Dans ce guide

Visites interactives de l'interface

Ouvrir dans le guide en 6 phases

Inspectez les écrans exacts du tableau de bord et les zooms annotés liés à ce guide.

Focus interface zoomé1 / 2
Éléments clés de l'interface

Limites d'émission et contrôles d'accès (Zoom)

Configurez une émission illimitée ou limitée, les canaux d'accès, le routage Wallet et des sécurités comme le blocage du re-téléchargement et la déduplication des destinataires.

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é :

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE SYSTÈME : CONTRÔLES D'ENVOI & DIFFUSION MULTICANAL
ÉTAPE 01 CONCEPTION DE CAMPAGNE & CONTRÔLE PRÉALABLE
1
Sélection d'audience : filtre par modèle, statut (ACTIVE) ou onlyUninstalled
2
Vérification des contrôles d'envoi (sendout-runtime.gates.ts) :
assertCustomerPaymentMethod : moyen de paiement valide ou solde positif
isManualPassEmailActive : bascule d'envoi activée sur le modèle
Contrôle des variables : impose la présence de {passDownloadUrl}
3
Estimation préalable (POST/api/v1/email-campaigns/estimate)
ÉTAPE 02 WORKER D'ENVOI ASYNCHRONE & MOTEUR DE MODÈLES
Charge le modèle d'e-mail & normalise automatiquement : {{...}}{...}
Hydrate {passDownloadUrl}, {appleWalletUrl}, {googleWalletUrl}
Injecte {unsubscribeLink} signé HMAC & les en-têtes RFC 8058
Applique la déduplication par idempotencyKey sur chaque passe destinataire
ÉTAPE 03A PASSERELLE D'ENVOI E-MAIL
Infrastructure e-mail gérée en UE (eu-central-1 Francfort)
Ou relais SMTP personnalisé chiffré
Tarif : 0,0005 € EUR par e-mail
ÉTAPE 03B PASSERELLE D'ENVOI SMS
Normalisation E.164 opérateur
Prise en charge Sender ID alpha
Tarif : 0,03 € EUR par segment
ÉTAPE 04 BOUCLE DE RETOUR & WEBHOOKS DE SUPPRESSION
Rejets & plaintes SES SNS (/api/v1/webhooks/ses)Suppression automatique
Pixel de suivi d'ouverture en temps réel (/email-campaigns/track/:id/open)
Journaux de livraison & flux d'activité (GET/delivery/history)

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 variableTypeDescription technique & valeur rendue
{passDownloadUrl}ObligatoireLien 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}AliasAlias hérités reconnus et normalisés automatiquement vers {passDownloadUrl}.
{appleWalletUrl}Direct plateformeLien direct servant le bundle Apple Wallet .pkpass brut (application/vnd.apple.pkpass).
{googleWalletUrl}Direct plateformeLien direct d'enregistrement dans Google Wallet (https://pay.google.com/gp/v/save/<jwt>).
{walletButtonText}Chaîne localiséeLibellé de bouton localisé (par ex. « Ajouter à Wallet », « Zu Apple Wallet hinzufügen »).
{firstName}, {lastName}, {name}ContactNom du destinataire extrait des attributs client.
{passFlowLink}InscriptionLien 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éeToute 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 :

HTTP
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 :

CanalTarif plateformeUnité de facturationRemarques
E-mail0,0005 € EURPar e-mail livréInclut le routage SES, le suivi des rejets et le suivi d'ouverture
SMS0,03 € EURPar segment GSM-7 de 160 car.Routage opérateur mobile international pour la livraison SMS
Mises à jour push0,00 € (GRATUIT)Pushs illimitésLes 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. 1
    Accédez à Passes -> Créer un passe individuel (Create Individual Pass).
  2. 2
    Saisissez les attributs du client (firstName, email, etc.).
  3. 3
    Cochez la case « Envoyer par e-mail » (Send by Email) dans la fenêtre d'émission.
  4. 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éthodeChemin de l'endpointPortée d'authentificationDescription
POST/api/v1/passes/:id/send-emailClé 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-templateClé API (passes)Envoie l'e-mail d'un passe unique avec un templateId et une idempotencyKey spécifiques.
POST/api/v1/passes/:passId/send-smsClé API (passes)Envoie un SMS pour un passe unique au phoneNumber destinataire.
POST/api/v1/email-campaignsClé API (delivery)Crée un brouillon de campagne d'envoi par lot.
POST/api/v1/email-campaigns/estimateClé 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/startClé API (delivery)Met la campagne en file pour exécution immédiate en arrière-plan.
GET/delivery/balanceClé API (billing)Retourne le solde prépayé de messagerie actuel et la devise.
POST/delivery/top-upClé API (billing)Crée une session Stripe Checkout pour acheter des crédits de messagerie.
GET/email-campaigns/track/:id/openPublicPixel de suivi transparent enregistrant l'horodatage d'ouverture des e-mails.

Documentation connexe

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.