Ignorar e ir ao conteúdo principal

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 visualizar todos os pontos de extremidade disponíveis e seus requisitos, clique na guia Pontos de extremidade na parte superior deste artigo.

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).

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 de engajamentos de e-mail clicando na guia Pontos de extremidade na parte superior deste artigo.

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.

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:

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

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:

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.

Você pode recuperar e-mails individualmente ou em massa. Saiba mais sobre a recuperação em massa clicando na guia Pontos de extremidade na parte superior deste artigo.

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.

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:

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 massa clicando na guia Pontos de extremidade na parte superior deste artigo.

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

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}

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.

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 em massa clicando na guia Pontos de extremidade na parte superior deste artigo.