E-mail transacional

Se tiver o complemento de e-mail transacional, você pode enviar e-mails por um endereço IP dedicado para recibos de comércio eletrônico, atualizações de conta, alterações de termos de serviço e outras transações de negócios essenciais.

E-mails transacionais são para interações baseadas em relacionamento, ao contrário de e-mails de marketing, que normalmente são usados para promover conteúdo.

Há três maneiras de implementar o e-mail transacional:

• Configurar o e-mail transacional no aplicativo
• API SMTP
• API de envio único

O e-mail transacional enviado com a API SMTP é acionado automaticamente por critérios específicos, como fazer uma compra em um site de comércio eletrônico. Esta API integra-se com sistemas internos ou de terceiros para disparar o email e incorporar dados armazenados fora do HubSpot (por exemplo, informações de envio ou preço de compra). O e-mail é enviado do seu sistema, mas está conectado a códigos de rastreamento do HubSpot que permitem rastreamento de engajamento e medições completos.

Para enviar um e-mail usando a API SMTP, você precisa usar um token de API SMTP para obter credenciais de login para o servidor SMTP da HubSpot. Depois de fazer login no servidor, você pode enviar o e-mail pelo SMTP. Se você não criou tokens de API SMTP, precisará gerar um novo token antes. Se já tiver criado tokens de API SMTP, veja os diferentes métodos para obter seus tokens pela API. Depois de obter o token, saiba sobre como fazer login no servidor SMTP da HubSpot.

Todos os domínios que você usa como o Endereço de remetente dos seus e-mails precisam estar conectados como domínio de envio de e-mail no HubSpot. Você encontrará um erro se enviar e-mails transacionais pela API SMTP usando um domínio não autorizado a enviar em nome da sua conta da HubSpot.

Para criar um novo token de API SMTP, faça uma solicitação POST para /marketing/v3/transactional/smtp-tokens/.

O corpo da solicitação precisa ser um objeto formatado em JSON com as seguintes propriedades:

• createContact: indica se um contato deve ser criado para destinatários de e-mail.
• campaignName: um nome para a campanha associada ao token de API SMTP.

A resposta inclui um objeto de token SMTP, que contém:

• id: nome de usuário para fazer login no servidor SMTP da HubSpot.
• createdBy: endereço de e-mail do usuário que enviou a solicitação de criação do token.
• password: a senha para fazer login no servidor SMTP da HubSpot.
• emailCampaignId: identificador atribuído à campanha fornecida na solicitação de criação de token.
• createdAt: data/hora gerada quando um token é criado.
• createContact: indica se um contato deve ser criado para destinatários de e-mail.
• campaignName: o nome da campanha associado ao token.

Com o token criado, você pode fazer login no servidor SMTP da HubSpot usando os valores de id e senha.

A senha de um token só pode ser recuperada no momento da criação. Se você perder a senha ou quiser definir uma nova, será necessário redefinir a senha do token. 

Veja abaixo os métodos disponíveis para obter dados de token usando a API.

Para obter uma lista de tokens por nome de campanha, ou um token único por ID da campanha, faça uma solicitação GET para /marketing/v3/transactional/smtp-tokens.

Você também precisará incluir um parâmetro campaignName ou emailCampaignId com a solicitação. Você pode encontrar todos os detalhes da solicitação na guia Endpoints no canto superior deste artigo.

Detalhes da resposta

A resposta contém results e paging como campos de nível superior:

• results: uma coleção de SmtpApiTokenView contendo:
  • id: nome de usuário para fazer login no servidor SMTP da HubSpot.
  • createdBy: endereço de e-mail do usuário que enviou a solicitação de criação do token.
  • emailCampaignId: identificador atribuído à campanha fornecida na solicitação de criação de token.
  • createdAt: data/hora gerada quando um token é criado.
  • createContact: indica se um contato deve ser criado para destinatários de e-mail.
  • campaignName: o nome da campanha associado ao token.
• paging: contém um campo next.after que pode ser usado para solicitar mais resultados.

Para consultar um token API SMTP único por ID, faça uma solicitação GET para /marketing/v3/transactional/smtp-tokens/{tokenId}.

Detalhes da resposta

A resposta inclui SmtpApiTokenView, que contém:

• id: nome de usuário para fazer login no servidor SMTP da HubSpot.
• createdBy: endereço de e-mail do usuário que enviou a solicitação de criação do token.
• emailCampaignId: identificador atribuído à campanha fornecida na solicitação de criação de token.
• createdAt: data/hora gerada quando um token é criado.
• createContact: indica se um contato deve ser criado para destinatários de e-mail.
• campaignName: o nome da campanha associado ao token.

Depois de criar tokens, você pode redefinir uma senha ou excluir o token usando a API.

Para solicitar uma senha de token, faça uma solicitação POST para /marketing/v3/transactional/smtp-tokens/{tokenId}/password-reset.

A resposta inclui SmtpApiTokenView, que contém:

• id: nome de usuário para fazer login no servidor SMTP da HubSpot.
• createdBy: endereço de e-mail do usuário que enviou a solicitação de criação do token.
• emailCampaignId: identificador atribuído à campanha fornecida na solicitação de criação de token.
• createdAt: data/hora gerada quando um token é criado.
• createContact: indica se um contato deve ser criado para destinatários de e-mail.
• campaignName: o nome da campanha associado ao token.

Para excluir um token API SMTP único, faça uma solicitação DELETE para  /marketing/v3/transactional/smtp-tokens/{tokenId}. 

A resposta não inclui nenhum conteúdo.

Veja abaixo os detalhes para fazer login no servidor SMTP da HubSpot, usando o nome de usuário (id) e a senha fornecida pelo seu token.

• Hostname SMTP:
  • Se você não estiver com base na UE, use smtp.hubapi.com como nome do host.
  • Se você estiver na UE, use smtp-eu1.hubapi.com como nome do host.
• Porta SMTP:
  • Para STARTTLS, você pode usar a porta 25 ou 587.
  • Para TLS direto, use a porta 465.
• Nome do usuário SMTP: fornecido no campo ID
• Senha SMTP: fornecida no campo de senha

A API de envio único envia e-mails de modelo criados na ferramenta de e-mail do HubSpot usando uma solicitação POST formatada em JSON. Todos os e-mails enviados por essa API serão associados automaticamente aos registros de contatos com base no endereço de e-mail. Se não houver contato com um endereço de e-mail correspondente, um novo contato com esse e-mail será criado. Se quiser enviar e-mails sem criar contatos, use a API SMTP.

A API de envio único envia e-mails de modelo criados na ferramenta de e-mail do HubSpot usando uma solicitação POST formatada em JSON. Todos os e-mails enviados por essa API serão associados automaticamente aos registros de contatos com base no endereço de e-mail. Se não houver contato com um endereço de e-mail correspondente, um novo contato com esse e-mail será criado. Se quiser enviar e-mails sem criar contatos, use a API SMTP.

Primeiro, configure seu e-mail no HubSpot. Depois de criar o e-mail, você poderá definir os detalhes do destinatário, incluindo qualquer contato ou propriedades personalizadas configuradas no modelo de e-mail, no corpo da solicitação de API. Para fazer a solicitação da API, você precisará do ID do e-mail:

• Se você deixar o e-mail em rascunho sem publicá-lo, poderá obter o ID do e-mail no URL quando estiver no editor de e-mail. O ID é o valor numérico que precede o caractere de barra final (/) no URL (por exemplo, https://app.hubspot.com/email/{PORTAL_ID}/edit/{EMAIL_ID}/settings).

• Se publicar o e-mail, você poderá copiar o ID do e-mail a partir da página de detalhes do e-mail.

Para enviar um email com a API de envio único, faça uma solicitação POST para /marketing/v3/transactional/single-email/send.

A resposta contém os seguintes campo:

• requestedAt: a data/hora da solicitação de envio.

• statusId: um identificador que pode ser usado para consulta o status do envio.

• status: o status da solicitação de envio. Inclui PENDENTE, PROCESSANDO, CANCELADO e CONCLUÍDO.

Solicitar propriedades

O corpo da solicitação precisa ser um objeto formatado em JSON com as seguintes propriedades:

• emailId
• message
• contactProperties
• customProperties

emailId

O campo emailId contém o ID de conteúdo do e-mail transacional, que pode ser encontrado na ferramenta de e-mail do HubSpot.

message

O campo de mensagem é um objeto JSON contendo tudo que você deseja substituir. No mínimo, você deve incluir o campo to.

Campos de objeto de mensagem:

• to: o destinatário do email
• from: do cabeçalho "De" do email. Você pode definir um nome com o seguinte formato: "from":"Sender Name <sender@hubspot.com>"
• sendId: o ID de um envio específico. Apenas um e-mail com um determinado sendId será enviado por conta, então você pode incluir esse campo para evitar envios de e-mail duplicados.
• replyTo: uma lista JSON de valores de cabeçalho "Responder para" para o email.
• cc: uma lista JSON de endereços de email a enviar como Cc.
• bcc: uma lista JSON de endereços de e-mail para enviar como Cco.

contactProperties

O campo contactProperties é um mapa JSON dos valores de propriedade de contato. Cada valor de propriedade de contato contém um nome e valor. Cada propriedade será definida no registro do contato e será visível no modelo em:

Use essas propriedades quando quiser definir uma propriedade de contato enquanto estiver enviando o e-mail. Por exemplo, ao enviar um recibo, que você pode definir uma propriedade last_paid_date, pois o envio do recibo terá informações sobre o último pagamento.

customProperties

O campo customProperties é um mapa JSON das propriedades do valor-chave. Essas propriedades geralmente estão relacionadas ao próprio e-mail, não ao contato que recebe o e-mail. Elas não aparecerão na versão da página da Web do e-mail ou na exibição do e-mail na linha do tempo do contato. Essas propriedades também não são armazenadas no HubSpot e serão incluídas apenas no e-mail enviado.

Cada chave no campo customProperties pode ser referenciada no modelo usando uma expressão HubL para campos contidos na variável personalizada (por exemplo,{{custom.NAME_OF_PROPERTY}}).

Por exemplo, se o modelo de e-mail fizer referência a duas propriedades, purchaseUrl e productName, você poderá fornecer os valores associados a elas com o seguinte corpo de solicitação:

Você pode fazer referência a essas propriedades no modelo de e-mail:

O campo customProperties só permite matrizes quando usado com um conteúdo de e-mail programável. No seu modelo de e-mail, você pode fazer referência aos itens definidos em seu campo customProperties usando uma expressão HubL (por exemplo, usando um loop for para renderizar cada item em uma lista). Por exemplo, se o customProperties que você incluiu no corpo da solicitação foi estruturado como o seguinte trecho JSON abaixo:

Em seguida, você pode fazer referência aos valores de cada item em exampleArray com o código HubL a seguir:

Uma vez enviado, o e-mail transacional tornaria o conteúdo do modelo de e-mail programável associado da seguinte forma:

Para obter o status do envio de e-mail, faça uma solicitação GET para https://api.hubapi.com/marketing/v3/email/send-statuses/{statusId}. 

A resposta contém os seguintes campo:

• sendResult: uma enumeração que representa o status de envio do e-mail. Os valores possíveis estão listados abaixo.
• requestedAt: a data/hora da solicitação do envio.

• startedAt: a data/hora de início do processamento do envio.

• completedAt: a data/hora de conclusão do envio.

• statusId: um identificador que pode ser usado para consulta o status do envio.

• status: o status da solicitação de envio. Inclui PENDENTE, PROCESSANDO, CANCELADO e CONCLUÍDO.

• eventId: se enviado, o ID e data/hora de criação do evento de envio.

sendResult

O sendResult é uma enumeração que reflete o resultado de uma tentativa de envio de e-mail. Os valores possíveis são:

• SENT: o e-mail foi enviado com sucesso.
• QUEUED: o e-mail foi colocado na fila e será enviado à medida que a fila é processada.
• PORTAL_SUSPENDED: devido a violações da Política de Utilização Responsável, o email do cliente do HubSpot foi suspenso.
• INVALID_TO_ADDRESS: o endereço do destinatário é inválido. Esse erro também ocorrerá se você tentar enviar um e-mail com um dos seguintes prefixos baseados em função no endereço de e-mail: abuse, no-reply, noreply, root, spam, security, undisclosed-recipients, unsubscribe, inoc, postmaster ou privacy.
• BLOCKED_DOMAIN: o domínio não pode receber e-mails do HubSpot neste momento.
• PREVIOUSLY_BOUNCED: o destinatário foi rejeitado anteriormente e a lógica de envio resultou em nenhum envio.
• PREVIOUS_SPAM: o destinatário marcou um email semelhante como spam.
• INVALID_FROM_ADDRESS: o endereço de Remetente é inválido.
• MISSING_CONTENT: o emailId é inválido, ou emailId corresponde a um email que não foi configurado para envio único.
• MISSING_TEMPLATE_PROPERTIES: há propriedades configuradas no modelo que não foram incluídas no customProperties enviado na solicitação.