Zum Hauptinhalt springen
Última modificação: 2 de dezembro de 2025

Run in Postman
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:
CampoDescrição
hs_timestampObrigató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_idO 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_directionA 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_htmlO corpo de um e-mail se ele for enviado de um registro do CRM.
hs_email_statusO status de envio do e-mail O valor pode ser BOUNCED, FAILED, SCHEDULED, SENDING ou SENT.
hs_email_subjectA linha de assunto do e-mail registrado.
hs_email_textO corpo do e-mail.
hs_attachment_idsOs IDs dos anexos do e-mail. Vários IDs de anexo são separados por ponto e vírgula.
hs_email_headersOs 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.
CampoDescrição
hs_email_from_emailEndereço de e-mail do remetente do e-mail
hs_email_from_firstnameNome do remetente do e-mail.
hs_email_from_lastnameSobrenome do remetente do e-mail.
hs_email_to_emailEndereços de e-mail dos destinatários
hs_email_to_firstnamePrimeiros nomes dos destinatários do e-mail
hs_email_to_lastnameSobrenomes 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": "[email protected]",
    "firstName": "FromFirst",
    "lastName": "FromLast"
  },
  "to": [
    {
      "email": "ToFirst ToLast<[email protected]>",
      "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\":\"[email protected]\",\"firstName\":\"FromFirst\",\"lastName\":\"FromLast\"},\"sender\":{\"email\":\"[email protected]\",\"firstName\":\"SenderFirst\",\"lastName\":\"SenderLast\"},\"to\":[{\"email\":\"ToFirst+ToLast<[email protected]>\",\"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:
CampoDescrição
toO registro que deseja associar ao e-mail, especificado por seu valor de id exclusivo.
typesO 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çãoParâmetro
propertiesUma lista separada por vírgulas das propriedades a serem retornadas.
associationsUma 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çãoParâmetro
limitO número máximo de resultados a serem exibidos por página.
propertiesUma 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:
CampoDescrição
emailIdO ID do e-mail.
toObjectTypeO tipo de objeto ao qual você deseja associar o e-mail (por exemplo, contato ou empresa)
toObjectIdO ID do registro ao qual você deseja associar o e-mail.
associationTypeIdUm 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.