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:
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 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
.
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.
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:
xxxxxxxxxx
//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\":[]}"
}
}
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:
xxxxxxxxxx
// 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. |
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çã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. |
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:
xxxxxxxxxx
// 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 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:
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
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.