mailinapp
Documentation menu

Salesforce

O MailInApp não tem um aplicativo do Salesforce para instalar — você não precisa de um. A própria API REST do Salesforce responde em JSON simples sobre HTTPS, e a fonte de dados via API do MailInApp com autenticação OAuth2 JWT Bearer foi criada para falar diretamente o fluxo de login servidor a servidor do Salesforce: sem tela de consentimento interativa, sem refresh token para gerenciar, e sua senha do Salesforce nunca chega ao MailInApp.

Este guia configura uma conexão somente leitura — trazendo linhas de Opportunity, Account ou Contact para tags de personalização, blocos de repetição e blocos de gráfico vinculados ao vivo. Ele não grava de volta no Salesforce.

Como funciona a conexão

  1. O MailInApp assina uma asserção JWT de curta duração com a chave privada do seu Connected App do Salesforce.
  2. Ele faz um POST dessa asserção para o endpoint de token do Salesforce, que verifica a assinatura em relação ao certificado que você enviou e retorna um token de acesso — nenhum nome de usuário ou senha é enviado, nunca.
  3. O MailInApp armazena o token de acesso em cache e chama a API REST do Salesforce (uma consulta SOQL) usando-o como token Bearer, renovando automaticamente antes que o token expire ou caso uma chamada retorne como não autorizada.

Cada etapa acontece no servidor, a cada busca — não há nada para manter ativo ou reautorizar manualmente depois de configurado.

Configure o lado do Salesforce

  1. No Salesforce Setup, vá em App Manager → New Connected App (ou New Connected App (Lightning)).
  2. Preencha os campos básicos de nome/e-mail e marque Enable OAuth Settings.
  3. Em Use digital signatures, envie um certificado. Se você ainda não tiver um, gere um certificado autoassinado e sua chave privada RSA correspondente — o certificado vai para o Salesforce, a chave privada vai para o MailInApp. Guarde a chave privada em um lugar seguro; você vai colá-la no MailInApp uma única vez, e depois ela fica mascarada.
  4. Adicione o escopo OAuth de que sua integração precisa — api (Manage user data via APIs) já é suficiente para leitura de registros.
  5. Salve e depois edite as políticas do Connected App: defina Permitted Users como Admin approved users are pre-authorized. É isso que torna o fluxo não interativo — sem essa configuração, o Salesforce espera que um humano passe por uma tela de consentimento, o que uma troca JWT servidor a servidor não consegue fazer.
  6. Atribua o usuário de integração (um usuário real do Salesforce com acesso à API habilitado no perfil, ou um usuário dedicado só para integração) ao Connected App por meio de um conjunto de permissões.
  7. Anote o Consumer Key do Connected App — é o issuer que o MailInApp precisa — e a URL My Domain da sua organização (Setup → My Domain), por exemplo https://yourorg.my.salesforce.com.

Conecte no MailInApp

Em Fontes de Dados → + Conexão de API, defina:

  • Endpoint — a URL de consulta REST da sua organização, por exemplo https://yourorg.my.salesforce.com/services/data/v61.0/query?q=SELECT+Name,Amount,StageName,CloseDate+FROM+Opportunity+WHERE+IsClosed+=+false (uma consulta SOQL codificada como URL — veja Consultando com SOQL abaixo).
  • Data path — records. A resposta de consulta do Salesforce envolve as linhas reais em um array records, junto com os campos totalSize/done.
  • Autenticação — OAuth2 JWT Bearer:
    • URL de token — https://login.salesforce.com/services/oauth2/token para organizações de produção e Developer Edition, e https://test.salesforce.com/services/oauth2/token para um sandbox.
    • Emissor — o Consumer Key do Connected App.
    • Sujeito — o nome de usuário do Salesforce do usuário de integração (a identidade que o JWT declara).
    • Audiência — o mesmo host da URL de token: https://login.salesforce.com (ou https://test.salesforce.com para um sandbox).
    • Chave privada — a chave privada RSA pareada com o certificado que você enviou ao Connected App.

Clique em Testar estas configurações para confirmar a conexão antes de salvar — isso gera um token real e pré-visualiza as primeiras linhas. Depois de salvar, use Testar conexão salva quando quiser verificar novamente sem colar a chave privada de novo.

Consultando com SOQL

A própria string de consulta do endpoint é o dado que você recebe de volta — não existe uma interface separada para "escolher seus campos", então molde a consulta SOQL para retornar exatamente as colunas que seu e-mail precisa:

SELECT Name, Amount, StageName, CloseDate FROM Opportunity WHERE IsClosed = false

Algumas coisas vale saber sobre o formato do que volta:

  • Somente campos simples (flat). Um campo de relacionamento como Owner.Email ou Account.Name volta como um objeto JSON aninhado ({"Owner": {"Email": "..."}}), e o interpretador de linhas do MailInApp descarta valores aninhados em vez de tentar adivinhar como achatá-los. Se você precisa de um identificador de proprietário ou de conta como tag de personalização utilizável, selecione um campo simples em vez disso — OwnerId, por exemplo — em vez de um caminho de relacionamento com ponto.
  • Até 1.000 linhas por busca. Suficiente para um e-mail de resumo ou dashboard; restrinja ainda mais com WHERE/ORDER BY/LIMIT na própria consulta se você quiser apenas um recorte específico.
  • Buscado direto a cada renderização. Um envio recorrente executa a consulta novamente e renderiza de novo os blocos vinculados com as linhas atuais do Salesforce a cada envio — não há cache além do próprio token OAuth.

Usando os dados

Depois de conectado, adicione-o a um projeto pelo painel de Dados do estúdio, com um alias (por exemplo, pipeline) e uma função:

  • Campos de personalização resolvem {{pipeline.field}} a partir da primeira linha retornada — útil para um único número de destaque.
  • Linhas de repetição alimentam um bloco de repetição — uma linha por Opportunity, renderizada como lista ou tabela.
  • A função collection é o que os blocos de Scorecard de KPI, gráfico de barras, linha e pizza vinculam diretamente — um campo Value do Scorecard de KPI definido como Amount com um agregado de Soma te dá um número "total do pipeline em aberto" ao vivo, sem nenhuma manipulação de tags de personalização, e um gráfico de barras agrupado por StageName transforma a mesma consulta em uma distribuição de pipeline por estágio.

Veja E-mail interativo alimentado por dados do Salesforce em tempo real para um exemplo completo — um resumo semanal de pipeline construído inteiramente a partir desta conexão.