Skip to content
Guida del Centro assistenza · Distribuzione passFase di onboarding 5
9 min di letturaVerificato 2026-11-16

Consegna via Email e SMS

Usa il Centro consegne, modelli email riutilizzabili, log bounce SES e configurazione SMTP personalizzata.

In questa guida

Guide visive interattive UI

Apri nella guida in 6 fasi

Esplora schermate reali della dashboard e dettagli ingranditi collegati a questa guida.

Focus UI ingrandito1 / 2
Elementi chiave dell'interfaccia

Limiti di emissione e controlli di accesso (Zoom)

Configura emissione illimitata o limitata, canali di accesso, routing Wallet e protezioni come il blocco del nuovo download dopo l'attivazione e la deduplicazione dei destinatari.

Messaggistica in uscita e architettura del Delivery Center

All'interno del Delivery Center (/delivery-center) puoi gestire invii transazionali di pass, campagne promozionali segmentate, Modelli e-mail riutilizzabili, liste di soppressione per le disiscrizioni e log di consegna in tempo reale.

Passinstance orchestra la messaggistica in uscita ad alto volume tramite code di job asincroni in background collegate all'infrastruttura e-mail gestita nell'UE (eu-central-1 Francoforte), alla consegna SMS tramite operatori mobili per gli SMS globali oppure al tuo relay SMTP personalizzato crittografato:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
CONTROLLI DI INVIO E DISTRIBUZIONE MULTICANALE
FASE 01 CREAZIONE CAMPAGNA E CONTROLLO PRE-FLIGHT
1
Selezione audience: filtra per modello, stato (ACTIVE) o onlyUninstalled
2
Controlli runtime di invio (sendout-runtime.gates.ts):
assertCustomerPaymentMethod: metodo di pagamento valido o saldo positivo
isManualPassEmailActive: interruttore di invio abilitato sul modello
Verifica segnaposto: impone la presenza di {passDownloadUrl}
3
Stima pre-flight (POST/api/v1/email-campaigns/estimate)
FASE 02 WORKER DI INVIO ASINCRONO E MOTORE MODELLI E-MAIL
Carica il modello e-mail e normalizza i segnaposto: {{...}}{...}
Popola {passDownloadUrl}, {appleWalletUrl}, {googleWalletUrl}
Inserisce {unsubscribeLink} firmato HMAC e header di disiscrizione RFC 8058
Applica deduplicazione idempotencyKey per ogni record pass destinatario
FASE 03A GATEWAY DI CONSEGNA E-MAIL
Infrastruttura e-mail gestita UE (eu-central-1 Francoforte)
Oppure Relay SMTP personalizzato
Tariffa: €0,0005 EUR per e-mail
FASE 03B GATEWAY DI CONSEGNA SMS
Normalizzazione E.164 operatori
Supporto Sender ID alfanumerico
Tariffa: €0,03 EUR per segmento SMS
FASE 04 FEEDBACK LOOP E WEBHOOK DI SOPPRESSIONE
Bounce e reclami SES SNS (/api/v1/webhooks/ses)Soppressione automatica
Pixel di tracciamento aperture (/email-campaigns/track/:id/open)
Log di consegna e flusso attività (GET/delivery/history)

Modelli e-mail e segnaposto canonici

I modelli riutilizzabili creati in Delivery Center -> Modelli (Email Template Engine) garantiscono coerenza di brand nelle notifiche transazionali, nei messaggi di benvenuto e negli avvisi di recupero pass.

Sintassi dei segnaposto e normalizzazione automatica

Passinstance adotta la sintassi a parentesi graffa singola: {placeholderName}. Se il tuo team di design inserisce doppie parentesi in stile Mustache o Handlebars ({{passDownloadUrl}}), il parser di Passinstance (normalizePlaceholders) le normalizza automaticamente in parentesi singole prima del salvataggio e del rendering.

Token segnapostoTipoDescrizione tecnica e valore renderizzato
{passDownloadUrl}ObbligatorioLo smart link di download canonico (passAccessUrl). Analizza il contesto del dispositivo destinatario per distribuire .pkpass su Apple Wallet o reindirizzare a Google Wallet.
{passUrl}, {passLink}, {smartLink}AliasAlias legacy riconosciuti e normalizzati automaticamente in {passDownloadUrl}.
{appleWalletUrl}Diretto piattaformaLink diretto che serve il pacchetto .pkpass di Apple Wallet (application/vnd.apple.pkpass).
{googleWalletUrl}Diretto piattaformaLink diretto di salvataggio su Google Wallet (https://pay.google.com/gp/v/save/<jwt>).
{walletButtonText}Stringa localizzataEtichetta del pulsante localizzata (ad es. "Add to Wallet", "Zu Apple Wallet hinzufügen").
{firstName}, {lastName}, {name}ContattoNome del destinatario estratto dagli attributi del cliente.
{passFlowLink}IscrizioneLink pubblico di registrazione del PassFlow associato (/f/:url).
{unsubscribeLink}ConformitàLink di disiscrizione one-click firmato HMAC (GET /email/unsubscribe/:token).
{attributeName}Proprietà personalizzataQualsiasi chiave di attributo personalizzato definita sul modello (ad es. {membershipNumber}, {tier}, {balance}).

Conformità RFC 8058 per la disiscrizione one-click

Per gli invii di marketing, Passinstance inserisce automaticamente gli header e-mail conformi allo standard RFC 8058:

HTTP
List-Unsubscribe: <https://api.passinstance.com/email/unsubscribe/{signedToken}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Questo abilita i pulsanti nativi "Annulla iscrizione" in Gmail, Apple Mail e Yahoo Mail, riducendo i reclami per spam e proteggendo la reputazione del dominio.


Invii via e-mail o SMS: flusso operativo del Delivery Center

Per avviare una campagna di distribuzione batch in uscita:

Passaggio 1: filtra la tua audience

In Delivery Center -> Nuova campagna, seleziona il modello del pass e applica i filtri di segmentazione:

  • Filtro stato: seleziona i pass attivi (status = 'ACTIVE').
  • Filtro non installati (onlyUninstalled: true): rivolgiti esclusivamente ai clienti che non hanno ancora aggiunto il pass a un dispositivo (installedDevices === 0).
  • Finestra data di creazione: seleziona i pass creati entro uno specifico intervallo temporale.

Passaggio 2: scegli il canale di consegna

  • E-mail: consegnata tramite la consegna e-mail gestita oppure tramite il tuo relay SMTP personalizzato.
  • SMS: consegnato tramite il servizio SMS di rete mobile verso numeri internazionali in formato E.164.

Passaggio 3: seleziona o componi il messaggio

Scegli un modello salvato in Delivery Center -> Modelli oppure redigi un messaggio ad hoc. Assicurati che {passDownloadUrl} sia presente nel corpo dell'e-mail.

Passaggio 4: esegui la stima pre-flight

Fai clic su Stima copertura (POST /api/v1/email-campaigns/estimate). Passinstance analizza l'audience e calcola:

  • Numero totale di pass corrispondenti.
  • Record e-mail/telefono validi.
  • Contatti soppressi (disiscritti e hard bounce esclusi).
  • Credito di messaggistica necessario.

Passaggio 5: avvia o pianifica l'invio

Fai clic su Avvia invio (POST /api/v1/email-campaigns/:id/start) per iniziare subito l'elaborazione in background tramite la coda di job, oppure imposta una data di invio futura.


Prezzi di consegna, saldo e ricarica crediti

La consegna dei messaggi in uscita viene fatturata con un modello trasparente a consumo:

CanaleTariffa piattaformaUnità di fatturazioneNote
E-mail€0,0005 EURPer e-mail consegnataInclude instradamento SES, monitoraggio bounce e tracciamento aperture
SMS€0,03 EURPer segmento GSM-7 da 160 caratteriInstradamento globale verso operatori mobili per consegna SMS
Aggiornamenti push€0,00 (GRATIS)Push illimitatiGli aggiornamenti push Apple APNs e Google Wallet sono sempre gratuiti

Monitoraggio del saldo e acquisto di crediti:

  • Controlla il saldo: visualizza il saldo disponibile nel Delivery Center oppure tramite GET /delivery/balance.
  • Ricarica crediti: fai clic su Aggiungi saldo (POST /delivery/top-up). Passinstance apre una sessione sicura Stripe Checkout per ricaricare l'account con carta di credito, SEPA o bonifico bancario.

Invio di singoli pass con consegna diretta via e-mail

Quando emetti manualmente un pass per un singolo cliente:

  1. 1
    Vai su Pass -> Crea pass individuale.
  2. 2
    Inserisci gli attributi del cliente (firstName, email, ecc.).
  3. 3
    Seleziona la casella "Invia tramite e-mail" nella finestra di emissione.
  4. 4
    Fai clic su Crea pass. Passinstance crea il record del pass e richiama immediatamente POST /passes/:id/email/send, inviando lo smart link personalizzato di download.

Puoi anche attivare un'e-mail per singolo pass in qualsiasi momento dalla vista di dettaglio del pass facendo clic su Azioni rapide -> Invia tramite e-mail (POST /passes/:passId/send-email-with-template).

Instradamento verificato tramite SMTP personalizzato

Se il workspace ha configurato un relay SMTP personalizzato (AddonType.OWN_SMTP), tutte le e-mail per singoli pass e gli invii di campagna transitano dal tuo server di posta invece che dall'infrastruttura SES predefinita di Passinstance.


Risoluzione dei problemi: il modello e-mail non viene inviato

Se un'e-mail non parte durante la creazione del pass, un invio manuale o l'esecuzione di una campagna, il blocco dipende dai controlli runtime applicati in sendout-runtime.gates.ts:

1. Segnaposto obbligatorio {passDownloadUrl} mancante

Se un modello richiede un URL del pass (requiresPassUrl), ma il contenuto non include {passDownloadUrl} (o un alias riconosciuto), il worker di invio si interrompe con BadRequestException. Soluzione: Modifica il modello nel Delivery Center e aggiungi {passDownloadUrl} nel corpo dell'e-mail.

2. Controllo metodo di pagamento del cliente (assertCustomerPaymentMethod)

Gli invii automatici richiedono che i workspace attivi dispongano di un metodo di pagamento verificato o di un saldo crediti positivo. Se l'abbonamento è scaduto o il saldo crediti è pari a zero, il gateway solleva PaymentRequiredException. Soluzione: Vai su Impostazioni -> Fatturazione -> Metodi di pagamento e aggiorna la carta oppure ricarica i crediti.

3. Attributi di contatto del destinatario mancanti

Se il record del pass ha il campo email nullo o vuoto, il worker salta il pass e registra un errore di validazione. Soluzione: Verifica che il record del pass contenga un indirizzo e-mail valido e correttamente formattato.

4. Interruttori di invio disattivati sul modello

In Impostazioni modello -> Distribuzione e invii, verifica che la modalità di invio desiderata sia abilitata:

  • adHocEmailEnabled === true (per invii rapidi manuali).
  • distributeOnCreate === true (per invio automatico alla generazione del pass).
  • downloadPageEmailEnabled === true (per richieste di inoltro da desktop a smartphone).

5. Oggetto o corpo del messaggio vuoti

Il controllo pre-flight isManualPassEmailContentReady rifiuta i messaggi in cui adHocEmailSubject o adHocEmailTemplate risultano vuoti.


Costi di invio SMS e configurazione del mittente personalizzato

Comprendere i costi per segmento SMS

I messaggi SMS sono tariffati a €0,03 EUR per segmento:

  • Codifica standard GSM-7: fino a 160 caratteri per segmento.
  • Codifica Unicode / UCS-2 (emoji, accenti speciali): fino a 70 caratteri per segmento.
  • Messaggi multi-segmento: i messaggi concatenati riservano 7 caratteri per segmento agli header di concatenazione (153 caratteri per GSM-7, 67 per Unicode).

Consiglio utile: Le notifiche push di Apple Wallet e Google Wallet sono gratuite al 100% e illimitate. Invia i pass iniziali via SMS o e-mail, quindi utilizza le notifiche push (changeMessage) per tutti gli aggiornamenti successivi azzerando i costi di messaggistica.

Configurazione dei Sender ID alfanumerici

In Impostazioni -> Messaggistica -> Impostazioni SMS, puoi impostare il nome della tua azienda come Sender ID SMS (senderProfile.smsSenderName, fino a 11 caratteri alfanumerici):

  • Europa, Regno Unito, Australia e la maggior parte dei mercati internazionali: i Sender ID alfanumerici sono supportati fin da subito senza preregistrazione. I clienti vedranno il nome della tua azienda (ad es. MYBRAND) come mittente.
  • Stati Uniti e Canada: gli operatori telefonici vietano rigorosamente i Sender ID alfanumerici non registrati. I messaggi verso USA e Canada vengono recapitati tramite numeri in pool conformi a 10DLC o short code dedicati.

Perché Passinstance non allega direttamente i file .pkpass alle e-mail

I merchant chiedono spesso perché le e-mail di Passinstance contengano uno smart link ({passDownloadUrl}) anziché allegare direttamente il file .pkpass grezzo. Esistono tre ragioni tecniche fondamentali:

1. Incompatibilità dei client e-mail Android (corruzione MIME)

I client di posta mobile su Android (incluse le app ufficiali Gmail e Outlook) non riconoscono il MIME type di Apple Wallet application/vnd.apple.pkpass. Quando un utente Android tocca un allegato .pkpass, il client lo interpreta come un archivio .zip grezzo, mostrando contenuti binari incomprensibili oppure l'errore "Impossibile aprire il file".

A differenza di Apple Wallet, Google Wallet non può importare file locali. Google Wallet richiede un URL cloud autenticato Aggiungi al Wallet (https://pay.google.com/gp/v/save/<signed_jwt>). Grazie agli smart link, gli utenti Android vengono reindirizzati automaticamente a Google Wallet senza alcun attrito.

3. Sicurezza su singolo dispositivo e telemetria

Un file .pkpass allegato a un'e-mail può essere inoltrato a centinaia di destinatari non autorizzati. Con gli smart link di download:

  • Puoi applicare l'Associazione a un solo dispositivo (limitToOneActivePerPass).
  • Puoi attivare la Protezione PIN e le Date di scadenza (enableDownloadUntil).
  • Raccogli la Telemetria completa del dispositivo (sistema operativo, browser, timestamp di installazione, attribuzione UTM) nel momento in cui il pass viene riscattato.

Riferimento REST API per la consegna

MetodoPercorso endpointAmbito AuthDescrizione
POST/api/v1/passes/:id/send-emailChiave API (passes)Invia un'e-mail transazionale per singolo pass utilizzando il modello predefinito.
POST/api/v1/passes/:passId/send-email-with-templateChiave API (passes)Invia un'e-mail per singolo pass con specifici templateId e idempotencyKey.
POST/api/v1/passes/:passId/send-smsChiave API (passes)Invia un SMS per singolo pass al phoneNumber del destinatario.
POST/api/v1/email-campaignsChiave API (delivery)Crea una bozza di campagna di invio batch.
POST/api/v1/email-campaigns/estimateChiave API (delivery)Restituisce dimensione dell'audience, numero di pass raggiungibili e crediti richiesti.
POST/api/v1/email-campaigns/:id/startChiave API (delivery)Accoda la campagna per l'esecuzione immediata in background.
GET/delivery/balanceChiave API (billing)Restituisce il saldo prepagato corrente per la messaggistica e la valuta.
POST/delivery/top-upChiave API (billing)Crea una sessione Stripe Checkout per acquistare crediti di messaggistica.
GET/email-campaigns/track/:id/openPubblicoPixel trasparente di tracciamento che registra i timestamp di apertura delle e-mail.

Documentazione correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.