Engajamentos | E-mail - HubSpot docs

Run in Postman

Requisitos de escopo

Use a API de engajamento de e-mail para registrar e gerenciar e-mails nos registros do CRM. Você pode registrar atividades de e-mail no HubSpot ou por meio da API de e-mails. Abaixo, aprenda os métodos básicos de gerenciamento de e-mails por meio da API. Para exibir todos os endpoints disponíveis e seus requisitos, verifique a documentação de referência.

Criar um email

Para criar um engajamento de e-mail, envie uma solicitação POST para /crm/v3/objects/emails. No corpo da solicitação, adicione detalhes do e-mail em um objeto de propriedades. Você também pode adicionar um objeto de associações para associar seu novo e-mail a um registro existente (por exemplo, contatos, empresas).

Propriedades

No objeto de propriedades, você pode incluir os seguintes campos:

Campo	Descrição
`hs_timestamp`	Obrigatório. Este campo marca a hora de criação do e-mail e determina onde ele se encontra na linha do tempo do registro. Você pode usar um carimbo de data e hora do Unix em milissegundos ou no formato UTC.
`hubspot_owner_id`	O ID do proprietário associado ao e-mail. Este campo determina o usuário listado como o criador do e-mail na linha do tempo do registro.
`hs_email_direction`	A direção em que o e-mail foi enviado Os valores possíveis incluem:`EMAIL`: o e-mail foi enviado do CRM ou enviado e registrado no CRM com o endereço Cco.`INCOMING_EMAIL`: o e-mail era uma resposta a um e-mail de saída registrado. `FORWARDED_EMAIL`: o e-mail foi encaminhado para o CRM.
`hs_email_html`	O corpo de um e-mail se ele for enviado de um registro do CRM.
`hs_email_status`	O status de envio do e-mail O valor pode ser `BOUNCED`, `FAILED`, `SCHEDULED`, `SENDING` ou `SENT`.
`hs_email_subject`	A linha de assunto do e-mail registrado.
`hs_email_text`	O corpo do e-mail.
`hs_attachment_ids`	Os IDs dos anexos do e-mail. Vários IDs de anexo são separados por ponto e vírgula.
`hs_email_headers`	Os cabeçalhos do e-mail. O valor dessa propriedade preencherá automaticamente determinadas propriedades de e-mail somente leitura. Saiba como definir cabeçalhos de e-mail.

Saiba mais sobre a criação em lote de engajamentos de e-mail na documentação de referência.

Propriedades somente leitura

Há também algumas propriedades de e-mail que são somente leitura e que são preenchidas automaticamente pelo HubSpot. As propriedades na tabela abaixo são preenchidas automaticamente a partir do valor hs_email_headers.

Campo	Descrição
`hs_email_from_email`	Endereço de e-mail do remetente do e-mail
`hs_email_from_firstname`	Nome do remetente do e-mail.
`hs_email_from_lastname`	Sobrenome do remetente do e-mail.
`hs_email_to_email`	Endereços de e-mail dos destinatários
`hs_email_to_firstname`	Primeiros nomes dos destinatários do e-mail
`hs_email_to_lastname`	Sobrenomes dos destinatários do e-mail.

Observação: ao recuperar um cabeçalho de e-mail, observe que há valores para From e Sender. Geralmente são os mesmos, mas como Sender identifica quem realmente enviou um e-mail, há situações em que os valores podem ser diferentes. Por exemplo, se um e-mail for enviado de um alias de e-mail, o valor From fará referência ao Endereço de e-mail real do usuário e o valor Sender fará referência ao alias de e-mail.

Definir cabeçalhos do e-mail

Como os cabeçalhos preenchem automaticamente as propriedades somente leitura, convém definir manualmente os cabeçalhos de e-mail. Para definir o valor hs_email_headers, você pode usar uma string com escape JSON com os seguintes dados:

//Example data
{
  "from": {
    "email": "from@domain.com",
    "firstName": "FromFirst",
    "lastName": "FromLast"
  },
  "to": [
    {
      "email": "ToFirst ToLast<to@test.com>",
      "firstName": "ToFirst",
      "lastName": "ToLast"
    }
  ],
  "cc": [],
  "bcc": []
}

Por exemplo, sua solicitação para criar um e-mail pode ter a seguinte aparência:

//Example request body
{
  "properties": {
    "hs_timestamp": "2019-10-30T03:30:17.883Z",
    "hubspot_owner_id": "47550177",
    "hs_email_direction": "EMAIL",
    "hs_email_status": "SENT",
    "hs_email_subject": "Let's talk",
    "hs_email_text": "Thanks for youremail",
    "hs_email_headers": "{\"from\":{\"email\":\"from@domain.com\",\"firstName\":\"FromFirst\",\"lastName\":\"FromLast\"},\"sender\":{\"email\":\"sender@domain.com\",\"firstName\":\"SenderFirst\",\"lastName\":\"SenderLast\"},\"to\":[{\"email\":\"ToFirst+ToLast<to@test.com>\",\"firstName\":\"ToFirst\",\"lastName\":\"ToLast\"}],\"cc\":[],\"bcc\":[]}"
  }
}

Associações

Para criar e associar um e-mail a registros existentes, inclua um objeto de associações na solicitação. Por exemplo, para criar um e-mail e associá-lo a um negócio e a um contato, o corpo da solicitação pode ser semelhante ao seguinte:

// Example request body
{
  "properties": {
    "hs_timestamp": "2019-10-30T03:30:17.883Z",
    "hubspot_owner_id": "11349275740",
    "hs_email_direction": "EMAIL",
    "hs_email_status": "SENT",
    "hs_email_subject": "Let's talk",
    "hs_email_text": "Thanks for your interest let's find a time to connect"
  },
  "associations": [
    {
      "to": {
        "id": 601
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 210
        }
      ]
    },
    {
      "to": {
        "id": 602
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 198
        }
      ]
    }
  ]
}

No objeto de associações, você deve incluir o seguinte:

Campo	Descrição
`to`	O registro que deseja associar ao e-mail, especificado por seu valor de `id` exclusivo.
`types`	O tipo de associação entre o e-mail e o registro. Inclua `associationCategory` e `associationTypeId`. Os IDs de tipo de associação padrão são listados aqui, ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da API de associações.

Recuperar e-mails

Você pode recuperar e-mails individualmente ou em massa. Saiba mais sobre a recuperação em lote na documentação de referência. Para recuperar um e-mail individual pelo seu ID, faça uma solicitaçãoGET para /crm/v3/objects/emails/{emailId}. Você também pode incluir os seguintes parâmetros no URL da solicitação:

Descrição	Parâmetro
`properties`	Uma lista separada por vírgulas das propriedades a serem retornadas.
`associations`	Uma lista separada por vírgulas de tipos de objeto para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a API de associações.

Para solicitar uma lista de todos os e-mails, faça uma solicitação GET para crm/v3/objects/emails. Você pode incluir os seguintes parâmetros na URL da solicitação:

Descrição	Parâmetro
`limit`	O número máximo de resultados a serem exibidos por página.
`properties`	Uma lista separada por vírgulas das propriedades a serem retornadas.

Atualizar e-mails

Você pode atualizar e-mails individualmente ou em massa. Para atualizar um e-mail individual pelo seu ID, faça uma solicitaçãoPATCH para /crm/v3/objects/emails/{emailId}. No corpo da solicitação, inclua as propriedades de e-mail que deseja atualizar. Por exemplo, o corpo da sua solicitação pode ser parecido com o seguinte:

// Example request body
{
  "properties": {
    "hs_timestamp": "2019-10-30T03:30:17.883Z",
    "hubspot_owner_id": "11349275740",
    "hs_email_direction": "EMAIL",
    "hs_email_status": "SENT",
    "hs_email_subject": "Let's talk tomorrow",
    "hs_email_text": "Thanks for your interest let's find a time to connect!"
  }
}

O HubSpot ignorará valores para propriedades somente leitura e inexistentes. Para limpar um valor de propriedade, passe uma string vazia para a propriedade no corpo da solicitação. Saiba mais sobre a atualização em lotes na documentação de referência.

Associar chamadas existentes a registros

Para associar um e-mail a registros, como um contato e suas empresas associadas, faça uma solicitação PUT para /crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}. A URL da solicitação contém os campos a seguir:

Campo	Descrição
`emailId`	O ID do e-mail.
`toObjectType`	O tipo de objeto ao qual você deseja associar o e-mail (por exemplo, contato ou empresa)
`toObjectId`	O ID do registro ao qual você deseja associar o e-mail.
`associationTypeId`	Um identificador exclusivo para indicar o tipo de associação entre o e-mail e o outro objeto. O ID pode ser representado numericamente ou em maiúsculas (por exemplo, `email_to_contact`). Você pode recuperar o valor por meio da API de associações.

Por exemplo, a URL da sua solicitação pode ser parecida com o seguinte: https://api.hubspot.com/crm/v3/objects/emails/17691787884/associations/contact/104901/198

Remover uma associação

Para remover uma associação entre um e-mail e um registro, faça uma solicitação DELETE para o mesmo URL acima: /crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

Fixar um e-mail em um registro

Você pode fixar um e-mail em um registro para que permaneça no topo da linha do tempo do registro. A chamada já deve estar associada ao registro antes da fixação e você só pode fixar uma atividade por registo. Para fixar um e-mail, inclua o id do e-mail no campo hs_pinned_engagement_id ao criar ou atualizar um registro por meio das APIs de objeto. Saiba mais sobre como usar as APIs de empresas,contatos, negócios, tickets e objetos personalizados.

Excluir e-mails

Quando você exclui um e-mail, ele é excluído permanentemente e não pode ser restaurado. Você pode recuperar e-mails individualmente ou em lotes. Para excluir um e-mail individual pelo seu ID, faça uma solicitaçãoDELETE para /crm/v3/objects/emails/{emailId}. Saiba mais sobre a exclusão de e-mails na documentação de referência.

Conta e configurações

Gerenciamento de aplicativo

Autenticação

Automação

CMS

Preferências de comunicação

Conversas

CRM

Data Studio

Eventos

Arquivos

Marketing

Reuniões

Receita

Webhooks

Diário de Webhooks

Engajamentos | E-mail

Run in Postman

Criar um email

Propriedades

Propriedades somente leitura

Definir cabeçalhos do e-mail

Associações

Recuperar e-mails

Atualizar e-mails

Associar chamadas existentes a registros

Remover uma associação

Fixar um e-mail em um registro

Excluir e-mails

Run in Postman

​Criar um email

​Propriedades

​Propriedades somente leitura

​Definir cabeçalhos do e-mail

​Associações

​Recuperar e-mails

​Atualizar e-mails

​Associar chamadas existentes a registros

​Remover uma associação

​Fixar um e-mail em um registro

​Excluir e-mails

Criar um email

Propriedades

Propriedades somente leitura

Definir cabeçalhos do e-mail

Associações

Recuperar e-mails

Atualizar e-mails

Associar chamadas existentes a registros

Remover uma associação

Fixar um e-mail em um registro

Excluir e-mails