> ## Documentation Index > Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Engajamentos | E-mail > **[Run in Postman](https://app.getpostman.com/run-collection/dd75d149eaa15806754f)** > **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](https://knowledge.hubspot.com/pt/records/manually-log-activities-on-records) 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](https://br.developers.hubspot.com/docs/api-reference/crm-emails-v3/guide.md). ## 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](https://br.developers.hubspot.com/docs/api-reference/crm-crm-owners-v3/guide.md) 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.](https://knowledge.hubspot.com/pt/connected-email/log-email-in-your-crm-with-the-bcc-or-forwarding-address)`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.](https://knowledge.hubspot.com/pt/connected-email/log-email-in-your-crm-with-the-bcc-or-forwarding-address) | | `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](https://br.developers.hubspot.com/docs/api-reference/crm-emails-v3/guide.md#set-email-headers). | Saiba mais sobre a criação em lote de engajamentos de e-mail na [documentação de referência](https://br.developers.hubspot.com/docs/api-reference/crm-emails-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fcreate). ### 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. | > [!WARNING] > > **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: ```json theme={null} //Example data { "from": { "email": "from@domain.com", "firstName": "FromFirst", "lastName": "FromLast" }, "to": [ { "email": "ToFirst ToLast", "firstName": "ToFirst", "lastName": "ToLast" } ], "cc": [], "bcc": [] } ``` Por exemplo, sua solicitação para criar um e-mail pode ter a seguinte aparência: ```json theme={null} //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\",\"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: ```json theme={null} // 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](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md#association-type-id-values), ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da [API de associações](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md#retrieve-association-types). | ## 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](https://br.developers.hubspot.com/docs/api-reference/crm-emails-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fread). Para recuperar um e-mail individual pelo seu ID, faça uma solicitação`GET` 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.](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v4/guide.md) | 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ção`PATCH` 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: ```json theme={null} // 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](https://br.developers.hubspot.com/docs/api-reference/crm-emails-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fupdate). ### 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](https://br.developers.hubspot.com/docs/api-reference/crm-associations-v3/guide.md). | 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](https://knowledge.hubspot.com/pt/records/pin-an-activity-on-a-record) 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,](https://br.developers.hubspot.com/docs/api-reference/crm-companies-v3/guide.md#pin-an-activity-on-a-company-record)[contatos](https://br.developers.hubspot.com/docs/api-reference/crm-contacts-v3/guide.md#pin-an-activity-on-a-contact-record), [negócios](https://br.developers.hubspot.com/docs/api-reference/crm-deals-v3/guide.md#pin-an-activity-on-a-deal-record), [tickets](https://br.developers.hubspot.com/docs/api-reference/crm-tickets-v3/guide.md#pin-an-activity-on-a-ticket-record) e [objetos personalizados](https://br.developers.hubspot.com/docs/api-reference/crm-custom-objects-v3/guide.md). ## 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ção`DELETE` para `/crm/v3/objects/emails/{emailId}`. Saiba mais sobre a exclusão de e-mails na [documentação de referência](https://br.developers.hubspot.com/docs/api-reference/crm-emails-v3/guide.md#delete-%2Fcrm%2Fv3%2Fobjects%2Femails%2F%7Bemailid%7D).