Salesforce
O MailInApp não tem um app do Salesforce para instalar, e você não precisa de um. A API REST do Salesforce responde com JSON simples via HTTPS. A fonte de dados por API do MailInApp, com a autenticação OAuth2 JWT Bearer, fala diretamente o fluxo de login servidor a servidor do Salesforce: sem tela de consentimento, sem refresh token para cuidar, e sua senha do Salesforce nunca chega ao MailInApp.
Este guia configura uma conexão somente leitura. Ela traz linhas de Opportunity, Account, Contact ou produtos para tags de personalização, blocos de repetição e gráficos vinculados, e pode importar seus contatos do Salesforce como público. Ela não grava nada no Salesforce.
Como a conexão funciona
- O MailInApp assina uma asserção JWT de curta duração com a chave privada do seu app.
- Envia essa asserção ao endpoint de token do Salesforce, que confere a assinatura com o certificado enviado e devolve um token de acesso. Nenhum usuário ou senha é enviado.
- O MailInApp guarda o token em cache e chama a API REST do Salesforce (uma consulta SOQL) com ele. Ele obtém um novo antes de expirar, ou se uma chamada voltar sem autorização.
Tudo acontece no servidor, a cada busca. Depois de configurado, não há nada para manter ativo ou reautorizar.
Criar um par de chaves
O fluxo JWT precisa de um par de chaves RSA: o certificado vai para o Salesforce e a chave privada para o MailInApp. Se você não tiver um, gere um par autoassinado com OpenSSL:
openssl req -x509 -newkey rsa:2048 -nodes -keyout mailinapp.key -out mailinapp.crt -days 730 -subj "/CN=MailInApp"
Guarde mailinapp.key em local seguro. Você a cola uma vez no MailInApp e, a partir daí, ela fica mascarada.
Configurar o Salesforce
O Salesforce agora cria novas integrações como External Client Apps (novos Connected Apps ficam desativados por padrão em orgs recentes).
- No Setup, abra o External Client App Manager e clique em New External Client App.
- Preencha o nome (por exemplo MailInApp JWT), um e-mail de contato e deixe Distribution State em Local.
- Abra API (Enable OAuth Settings) e marque Enable OAuth. O fluxo JWT nunca usa a Callback URL, mas ela é obrigatória:
https://login.salesforce.com/services/oauth2/successserve. - Em OAuth Scopes, adicione Manage user data via APIs (api) e Perform requests at any time (refresh_token, offline_access).
- Em Flow Enablement, marque Enable JWT Bearer Flow e envie o certificado (
mailinapp.crt). Clique em Create. - Na aba Policies do app, clique em Edit. Em OAuth Policies, defina Permitted Users como Admin approved users are pre-authorized e selecione o perfil ou o permission set do usuário com que o MailInApp faz login. É isso que torna o fluxo não interativo: sem isso, o Salesforce espera que alguém confirme uma tela de consentimento. Salve.
- Na aba Settings, abra OAuth Settings e clique em Consumer Key and Secret. O Salesforce envia um código por e-mail para confirmar que é você e depois mostra a Consumer Key: é o emissor de que o MailInApp precisa. O secret não é necessário.
O usuário com que o MailInApp faz login vê exatamente o que esse usuário vê no Salesforce. A escolha mais limpa é um usuário de integração dedicado, com acesso de leitura aos objetos que seus e-mails usam. Um campo oculto para esse usuário (pela segurança em nível de campo) não aparece nos resultados.
Conectar no MailInApp
Vá em Fontes de dados → + Conexão por API e preencha:
- URL do endpoint: a URL de consulta da sua org com uma consulta SOQL, por exemplo
https://yourorg.my.salesforce.com/services/data/v62.0/query?q=SELECT Name, Amount, StageName, CloseDate, Account.Name FROM Opportunity WHERE IsClosed = false. Você pode digitar a consulta com espaços normais: o MailInApp a codifica. - Caminho dos dados:
records. O Salesforce entrega as linhas em um arrayrecords, ao lado detotalSizeedone. - Autenticação: OAuth2 JWT Bearer, com:
- URL do token:
https://login.salesforce.com/services/oauth2/token(ou a do seu My Domain,https://yourorg.my.salesforce.com/services/oauth2/token);https://test.salesforce.com/services/oauth2/tokenpara um sandbox. - Emissor: a Consumer Key do app.
- Assunto (subject): o nome de usuário do Salesforce com que o MailInApp faz login.
- Público (audience):
https://login.salesforce.com(https://test.salesforce.compara um sandbox). - Chave privada: o conteúdo de
mailinapp.key.
- URL do token:
Clique em Testar estas configurações: o MailInApp obtém um token real, executa a consulta e mostra as primeiras linhas como suas tags de personalização vão vê-las. Depois de salva, Testar conexão salva confere a conexão a qualquer momento sem colar a chave de novo.
Uma conexão é uma consulta. Crie uma por tarefa: as oportunidades abertas para um e-mail de pipeline, a tabela de preços para um catálogo, os contatos para um público.
Consultar com SOQL
A consulta é exatamente o dado que você recebe, então selecione só as colunas de que o e-mail precisa.
- Campos relacionados funcionam. O Salesforce devolve um campo de relacionamento como
Account.Namecomo objeto aninhado; o MailInApp o transforma em um campo chamadoAccount.Name. Escreva{{alias.Account.Name}}em uma tag de personalização, ou{{Account.Name}}dentro de um bloco de repetição. Funciona até três níveis (Account.Owner.Name), e os metadadosattributesque o Salesforce adiciona a cada registro ficam de fora. - Ordene e limite na consulta.
ORDER BY CloseDateeLIMIT 10definem a ordem e o número de linhas de um bloco de repetição. - Até 1.000 linhas por busca, o bastante para um resumo ou catálogo.
- Buscado de novo a cada renderização. Cada envio, inclusive cada execução de um envio recorrente, roda a consulta de novo, então o e-mail sempre mostra os dados atuais do Salesforce. Só o token OAuth fica em cache.
Algumas consultas úteis:
SELECT Name, StageName, Amount, CloseDate, NextStep, Account.Name FROM Opportunity WHERE IsClosed = false ORDER BY CloseDate
SELECT Name, ProductCode, UnitPrice, Product2.Description, Product2.DisplayUrl FROM PricebookEntry WHERE Pricebook2.IsStandard = true AND IsActive = true
SELECT Id, FirstName, LastName, Title, Email, HasOptedOutOfEmail, Account.Name, Account.Industry FROM Contact WHERE AccountId != null
Usar os dados
Adicione a conexão a um e-mail pelo painel Dados do estúdio, com um apelido (por exemplo pipeline) e uma função:
- Campos de mesclagem:
{{pipeline.campo}}vem da primeira linha. Bom para um número de destaque. - Linhas para repetir: alimentam um bloco de repetição, que repete o conteúdo para cada linha, por exemplo um cartão por produto.
- As mesmas linhas alimentam os gráficos de KPI, barras, linhas e pizza: um KPI que soma
Amounté um número de pipeline aberto ao vivo, e um gráfico de barras agrupado porStageNameé o pipeline por etapa.
Um recorte diferente para cada destinatário
Filtrar linhas em um bloco de repetição e o filtro de um gráfico podem comparar um campo do Salesforce com os dados do destinatário. Com uma lista de público que tenha a coluna company, a regra Account.Name é igual a {{company}} mostra a cada revendedor só as próprias oportunidades, a partir de uma única consulta compartilhada. A cópia de cada destinatário é gerada a partir da própria linha no momento do envio.
Importar seus contatos do Salesforce
Seu público é uma lista de contatos do MailInApp. Para preenchê-la a partir do Salesforce, crie uma conexão por API com uma consulta de Contact (a terceira acima) e depois vá em Contatos → Importar contatos e escolha Conexão por API.
O MailInApp lê as linhas com as credenciais salvas, reconhece os campos do Salesforce e oferece Usar mapeamento do Salesforce: FirstName → first_name, Account.Name → company, Id → salesforce_id e assim por diante. Um contato com Email Opt Out (HasOptedOutOfEmail) marcado no Salesforce é sinalizado na etapa de verificação, que oferece deixá-lo de fora. Um relatório do Salesforce exportado em CSV é reconhecido do mesmo jeito. Veja Importar leads.
A importação é uma cópia: rode-a de novo para trazer contatos novos.
Veja E-mail interativo com dados do Salesforce ao vivo para um exemplo completo: um resumo semanal do pipeline feito com esta conexão.
