Skip to content
Guia da Central de Ajuda · Distribuição de passesFase de integração 5
10 min de leituraVerificado 2026-11-16

Envio por e-mail e SMS

Utilize o Centro de Envios, modelos de e-mail reutilizáveis, monitorização SES e servidor SMTP próprio.

Neste guia

Inspecione capturas de ecrã exatas do painel e detalhes ampliados relacionados com este guia.

Foco ampliado da interface1 / 2
Elementos-chave da interface

Limites de emissão e controlos de acesso (Zoom)

Configure emissão ilimitada ou limitada, canais de acesso, encaminhamento de Wallet e proteções como bloquear nova transferência após ativação e desduplicar destinatários.

Arquitetura de mensagens de saída e Centro de Entrega

No Centro de Entrega (/delivery-center), pode gerir envios transacionais de passes, campanhas promocionais segmentadas, Modelos de E-mail reutilizáveis, listas de supressão de cancelamento de subscrição e registos de entrega em tempo real.

A Passinstance orquestra mensagens de saída em grande volume através de filas assíncronas de tarefas em segundo plano ligadas à infraestrutura europeia gerida de e-mail (eu-central-1 Frankfurt), à entrega de SMS por operadora para SMS global ou ao seu servidor de retransmissão SMTP personalizado encriptado:

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
PORTAS DE ENVIO E DISPARO MULTICANAL
ETAPA 01 CRIAÇÃO DE CAMPANHAS E VERIFICAÇÃO PRÉVIA
1
Seleção de Audiência: Filtrar por modelo, estado (ACTIVE) ou onlyUninstalled
2
Verificação de Portas de Execução (sendout-runtime.gates.ts):
assertCustomerPaymentMethod: Método de faturação válido ou saldo positivo
isManualPassEmailActive: Opção de envio ativada no modelo
Verificação de Marcador: Impõe a presença de {passDownloadUrl}
3
Estimativa Prévia (POST/api/v1/email-campaigns/estimate)
ETAPA 02 WORKER DE ENVIO ASSÍNCRONO E MOTOR DE MODELOS
Ingere Modelo de E-mail e normaliza marcadores: {{...}}{...}
Preenche {passDownloadUrl}, {appleWalletUrl}, {googleWalletUrl}
Injeta {unsubscribeLink} assinado por HMAC e cabeçalhos RFC 8058
Impõe desduplicação idempotencyKey por registo de passe do destinatário
ETAPA 03A GATEWAY DE ENTREGA E-MAIL
Infraestrutura gerida UE (`eu-central-
Ou Relé SMTP Personalizado Encriptado
Tarifa: €0.0005 EUR por e-mail
ETAPA 03B GATEWAY DE ENTREGA SMS
Normalização E.164 SMS operadora
Suporte a ID remetente alfanum.
Tarifa: €0.03 EUR por segm. SMS
ETAPA 04 CICLO DE FEEDBACK E WEBHOOKS DE SUPRESSÃO
Devoluções e Reclamações SES SNS (/api/v1/webhooks/ses)Auto-supressão
Píxel de Acompanhamento de Aberturas (/email-campaigns/track/:id/open)
Registos de Entrega e Fluxo de Atividade (GET/delivery/history)

Modelos de e-mail e marcadores de posição canónicos

Os modelos reutilizáveis criados em Centro de Entrega -> Modelos (Email Template Engine) garantem consistência de marca em notificações transacionais, mensagens de boas-vindas e alertas de recuperação de passes.

Sintaxe de marcadores de posição e normalização automática

A Passinstance impõe uma sintaxe de chaveta simples: {placeholderName}. Se a sua equipa de design introduzir chavetas duplas ao estilo Mustache ou Handlebars ({{passDownloadUrl}}), o analisador da Passinstance (normalizePlaceholders) normaliza-as automaticamente para chavetas simples antes do armazenamento e da renderização.

Token de marcador de posiçãoTipoDescrição técnica e valor renderizado
{passDownloadUrl}ObrigatórioA ligação inteligente canónica de transferência (passAccessUrl). Inspeciona o contexto do dispositivo do destinatário para transmitir o .pkpass da Apple Wallet ou redirecionar para a Google Wallet.
{passUrl}, {passLink}, {smartLink}AliasAliases legados reconhecidos e normalizados automaticamente para {passDownloadUrl}.
{appleWalletUrl}Direto por plataformaLigação direta que serve o pacote bruto .pkpass da Apple Wallet (application/vnd.apple.pkpass).
{googleWalletUrl}Direto por plataformaLigação direta para guardar na Google Wallet (https://pay.google.com/gp/v/save/<jwt>).
{walletButtonText}String localizadaRótulo de botão localizado (por exemplo, "Add to Wallet", "Zu Apple Wallet hinzufügen").
{firstName}, {lastName}, {name}ContactoNome do destinatário extraído dos atributos do cliente.
{passFlowLink}InscriçãoLigação pública de registo para o PassFlow associado (/f/:url).
{unsubscribeLink}ConformidadeLigação de cancelamento de subscrição com um clique assinada por HMAC (GET /email/unsubscribe/:token).
{attributeName}Propriedade personalizadaQualquer chave de atributo personalizado definida no modelo (por exemplo, {membershipNumber}, {tier}, {balance}).

Conformidade de cancelamento de subscrição com um clique RFC 8058

Nos envios de marketing, a Passinstance injeta automaticamente cabeçalhos de e-mail em conformidade com a norma RFC 8058:

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

Isto ativa botões nativos de "Cancelar subscrição" no Gmail, Apple Mail e Yahoo Mail, evitando reclamações de spam e protegendo a reputação do seu domínio.


Envios por e-mail ou SMS: Fluxo de trabalho no Centro de Entrega

Para lançar uma campanha de distribuição em lote:

Passo 1: Filtrar a sua audiência

Em Centro de Entrega -> Nova Campanha, selecione o seu modelo de passe e aplique filtros de segmento:

  • Filtro de Estado: Direcione para passes ativos (status = 'ACTIVE').
  • Filtro Não Instalados (onlyUninstalled: true): Direcione apenas para clientes que ainda não adicionaram o passe a um dispositivo (installedDevices === 0).
  • Janela de Data de Criação: Direcione para passes criados dentro de intervalos de datas específicos.

Passo 2: Escolher o canal de entrega

  • E-mail: Entregue através da entrega gerida de e-mail ou do seu servidor de retransmissão SMTP personalizado.
  • SMS: Entregue através de entrega de SMS por operadora para números móveis internacionais no formato E.164.

Passo 3: Selecionar ou redigir a sua mensagem

Escolha um modelo guardado em Centro de Entrega -> Modelos ou redija uma mensagem avulsa. Certifique-se de que {passDownloadUrl} está presente no corpo do e-mail.

Passo 4: Executar a estimativa prévia

Clique em Estimar Alcance (POST /api/v1/email-campaigns/estimate). A Passinstance analisa a sua audiência:

  • Total de passes correspondentes.
  • Registos válidos de e-mail/telefone.
  • Contactos suprimidos (cancelamentos de subscrição e devoluções permanentes excluídos).
  • Saldo de créditos de mensagens necessário.

Passo 5: Enviar ou agendar

Clique em Iniciar Envio (POST /api/v1/email-campaigns/:id/start) para iniciar o processamento imediato em segundo plano através da fila de tarefas ou defina uma data futura de publicação.


Preços de entrega, saldo e carregamento de créditos

A entrega de mensagens de saída é faturada num modelo transparente de pagamento consoante a utilização:

CanalTarifa da plataformaUnidade de faturaçãoNotas
E-mail€0.0005 EURPor e-mail entregueInclui encaminhamento SES, monitorização de devoluções e acompanhamento de aberturas
SMS€0.03 EURPor segmento GSM-7 de 160 carateresEncaminhamento global por operadoras móveis para entrega de SMS
Atualizações Push€0.00 (GRÁTIS)Envios push ilimitadosOs envios push Apple APNs e Google Wallet são sempre gratuitos

Monitorizar saldo e comprar créditos:

  • Consultar Saldo: Veja o seu saldo atual no Centro de Entrega ou através de GET /delivery/balance.
  • Carregar Créditos: Clique em Adicionar Saldo (POST /delivery/top-up). A Passinstance abre uma sessão segura Stripe Checkout que permite carregar a sua conta com cartão de crédito, SEPA ou transferência bancária.

Enviar passes individuais com entrega direta por e-mail

Ao emitir manualmente um passe para um cliente individual:

  1. 1
    Aceda a Passes -> Criar Passe Individual.
  2. 2
    Introduza os atributos do cliente (firstName, email, etc.).
  3. 3
    Marque a caixa "Enviar por E-mail" na janela de emissão.
  4. 4
    Clique em Criar Passe. A Passinstance cria o registo do passe e chama imediatamente POST /passes/:id/email/send, enviando a ligação inteligente personalizada de transferência.

Também pode acionar um e-mail para um passe individual em qualquer momento a partir da vista de detalhe do passe clicando em Ações Rápidas -> Enviar por E-mail (POST /passes/:passId/send-email-with-template).

Encaminhamento SMTP personalizado verificado

Se o seu espaço de trabalho tiver configurado um servidor de retransmissão SMTP personalizado (AddonType.OWN_SMTP), todos os e-mails de passes individuais e envios de campanhas são encaminhados através do seu próprio servidor de correio em vez da infraestrutura SES predefinida da Passinstance.


Resolução de problemas: O modelo de e-mail não está a ser enviado (Porque é que o meu modelo de e-mail não envia?)

Se um e-mail falhar no envio durante a criação do passe, o disparo manual ou a execução de uma campanha, a falha deve-se às portas de execução impostas em sendout-runtime.gates.ts:

1. Marcador de posição obrigatório {passDownloadUrl} em falta

Se um modelo estiver assinalado como exigindo um URL de passe (requiresPassUrl), mas o conteúdo do modelo não contiver {passDownloadUrl} (ou um alias aceite), o worker de envio interrompe a operação com BadRequestException. Solução: Edite o modelo no Centro de Entrega e adicione {passDownloadUrl} ao corpo do e-mail.

2. Porta de método de pagamento do cliente (assertCustomerPaymentMethod)

Os envios automatizados exigem que os espaços de trabalho ativos tenham um método de pagamento verificado registado ou um saldo positivo de créditos. Se a sua subscrição estiver em atraso ou o saldo de créditos for zero, a gateway devolve PaymentRequiredException. Solução: Aceda a Definições -> Faturação -> Métodos de Pagamento e atualize o seu cartão ou carregue créditos.

3. Atributos de contacto do destinatário em falta

Se o registo do passe de destino tiver o campo email nulo ou vazio, o worker ignora o passe e regista um erro de validação. Solução: Verifique se o registo do passe contém um endereço de e-mail válido e bem formatado.

4. Opções de envio desativadas no modelo

Em Definições do Modelo -> Distribuição e Envios, confirme que o modo de envio relevante está ativado:

  • adHocEmailEnabled === true (para envios rápidos manuais).
  • distributeOnCreate === true (para envio automático aquando da geração do passe).
  • downloadPageEmailEnabled === true (para pedidos de reenvio para telemóvel a partir do computador).

5. Linha de assunto ou corpo vazio

A porta prévia isManualPassEmailContentReady rejeita mensagens em que adHocEmailSubject ou adHocEmailTemplate esteja em branco.


Custo de envio de SMS e configuração de remetente personalizado

Compreender os custos por segmento de SMS

As mensagens SMS são faturadas a €0.03 EUR por segmento:

  • Codificação GSM-7 Padrão: Até 160 carateres por segmento.
  • Codificação Unicode / UCS-2 (Emojis, acentos especiais): Até 70 carateres por segmento.
  • Mensagens Multissegmento: As mensagens concatenadas reservam 7 carateres por segmento para cabeçalhos de concatenação (153 carateres para GSM-7, 67 para Unicode).

Dica profissional: As notificações push da Apple Wallet e da Google Wallet são 100% gratuitas e ilimitadas. Envie os passes iniciais por SMS ou e-mail e utilize notificações push (changeMessage) para atualizações subsequentes, eliminando os custos de mensagens.

Configurar IDs de remetente alfanuméricos

Em Definições -> Mensagens -> Definições de SMS, pode configurar o nome da sua empresa como ID de remetente de SMS (senderProfile.smsSenderName, até 11 carateres alfanuméricos):

  • Europa, Reino Unido, Austrália e Maioria dos Mercados Internacionais: Os IDs de remetente alfanuméricos são suportados de imediato sem pré-registo. Os clientes veem o nome da sua empresa (por exemplo, MYBRAND) como remetente.
  • Estados Unidos e Canadá: As operadoras de telecomunicações proíbem estritamente IDs de remetente alfanuméricos não registados. As mensagens para os EUA/Canadá são entregues através de números partilhados em conformidade com 10DLC ou códigos curtos dedicados.

Porque é que a Passinstance não anexa ficheiros .pkpass diretamente aos e-mails

Os comerciantes perguntam frequentemente por que razão os e-mails da Passinstance contêm uma ligação inteligente ({passDownloadUrl}) em vez de anexarem o ficheiro .pkpass em bruto diretamente ao e-mail. Existem três razões técnicas críticas:

1. Incompatibilidade dos clientes de e-mail Android (Corrupção MIME)

Os clientes de e-mail móveis no Android (incluindo as aplicações oficiais Gmail e Outlook) não reconhecem o tipo MIME da Apple Wallet application/vnd.apple.pkpass. Quando um utilizador Android toca num anexo .pkpass, o cliente de e-mail trata-o como um ficheiro .zip em bruto, apresentando conteúdo binário ilegível ou um erro indicando "Não é possível abrir o ficheiro".

2. A arquitetura da Google Wallet exige ligações JWT na cloud

Ao contrário da Apple Wallet, a Google Wallet não consegue importar ficheiros locais. A Google Wallet exige um URL autenticado na cloud para adicionar à carteira (https://pay.google.com/gp/v/save/<signed_jwt>). Ao utilizar ligações inteligentes, os utilizadores Android são automaticamente redirecionados para a Google Wallet sem fricção.

3. Segurança de dispositivo único e telemetria de dispositivos

Um ficheiro .pkpass em bruto anexado a um e-mail pode ser reencaminhado para centenas de destinatários não autorizados. Com ligações inteligentes de transferência:

  • Pode impor Vinculação a Dispositivo Único (limitToOneActivePerPass).
  • Pode impor Proteção por PIN e Datas de Expiração (enableDownloadUntil).
  • Capta Telemetria Completa do Dispositivo (sistema operativo, navegador, carimbo temporal de instalação, atribuição UTM) quando o passe é reclamado.

Referência da API REST de entrega

MétodoCaminho do endpointEscopo de autenticaçãoDescrição
POST/api/v1/passes/:id/send-emailChave API (passes)Envia um e-mail transacional de passe único utilizando o modelo predefinido.
POST/api/v1/passes/:passId/send-email-with-templateChave API (passes)Envia um e-mail de passe único com um templateId e idempotencyKey específicos.
POST/api/v1/passes/:passId/send-smsChave API (passes)Envia um SMS de passe único para o phoneNumber do destinatário.
POST/api/v1/email-campaignsChave API (delivery)Cria um rascunho de campanha de envio em lote.
POST/api/v1/email-campaigns/estimateChave API (delivery)Devolve o tamanho da audiência, a contagem de passes entregáveis e os créditos necessários.
POST/api/v1/email-campaigns/:id/startChave API (delivery)Coloca a campanha em fila para execução imediata em segundo plano.
GET/delivery/balanceChave API (billing)Devolve o saldo atual pré-pago de mensagens e a moeda.
POST/delivery/top-upChave API (billing)Cria uma sessão Stripe Checkout para comprar créditos de mensagens.
GET/email-campaigns/track/:id/openPúblicoPíxel transparente de acompanhamento que regista carimbos temporais de abertura de e-mails.

Documentação relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.