> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.fr/docs/llms.txt > Use this file to discover all available pages before exploring further. # Engagements | E-mail > Utilisez l'API d'engagement des e-mails pour enregistrer et gérer les e-mails dans les fiches d'informations du CRM. > **[Run in Postman](https://app.getpostman.com/run-collection/dd75d149eaa15806754f)** > **Exigences de portée** Utilisez l'API d'engagement des e-mails pour enregistrer et gérer les e-mails dans les fiches d'informations du CRM. Vous pouvez enregistrer des activités d'e-mails soit [dans HubSpot](https://knowledge.hubspot.com/fr/records/manually-log-activities-on-records) soit via l'API des e-mails. Découvrez ci-dessous les méthodes de base pour gérer les e-mails via l'API. Pour connaître tous les points de terminaison disponibles et leurs exigences, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-emails-v3/guide.md). ## Créer un e-mail Pour créer un engagement d'e-mail, effectuez une requête `POST` à `/crm/v3/objects/emails`. Dans le corps de la requête, ajoutez les détails d'e-mails dans un objet **properties**. Vous pouvez également ajouter un objet d'**association** pour associer votre nouvel e-mail à une fiche d'informations existante (par exemple, des contacts ou des entreprises). ### Propriétés Dans l'objet de propriété, vous pouvez inclure les champs suivants : | Champ | Description | | - | - | | `hs_timestamp` | Obligatoire. Ce champ indique l'heure de création de l'e-mail et détermine où se trouve l'e-mail sur la chronologie de la fiche d'informations. Vous pouvez utiliser soit un horodatage Unix en millisecondes, soit un format UTC. | | `hubspot_owner_id` | L'[ID du propriétaire](https://developers.hubspot.fr/docs/api-reference/crm-crm-owners-v3/guide.md) associé à l'e-mail. Ce champ détermine l'utilisateur listé comme le créateur de l'e-mail sur la chronologie de la fiche d'informations. | | `hs_email_direction` | La direction dans laquelle l'e-mail a été envoyé. Les valeurs possibles sont : `EMAIL` : l'e-mail a été envoyé depuis le CRM ou envoyé et enregistré dans le CRM avec [l'adresse CCI.](https://knowledge.hubspot.com/fr/connected-email/log-email-in-your-crm-with-the-bcc-or-forwarding-address)`INCOMING_EMAIL` : l'e-mail était une réponse à un e-mail sortant enregistré. `FORWARDED_EMAIL` : l'e-mail a été [transféré au CRM.](https://knowledge.hubspot.com/fr/connected-email/log-email-in-your-crm-with-the-bcc-or-forwarding-address) | | `hs_email_html` | Le corps d'un e-mail s'il est envoyé depuis un enregistrement CRM. | | `hs_email_status` | Le statut d'envoi de l'e-mail. La valeur peut être `BOUNCED`, `FAILED`, `SCHEDULED`, `SENDING`, ou `SENT`. | | `hs_email_subject` | La ligne d'objet de l'e-mail enregistré. | | `hs_email_text` | Le corps de l'e-mail. | | `hs_attachment_ids` | Les ID des pièces jointes de l'e-mail. Les ID de pièces jointes multiples sont séparés par un point-virgule. | | `hs_email_headers` | Les en-têtes de l'e-mail. La valeur de cette propriété renseignera automatiquement certaines propriétés d'e-mails en lecture seule. Découvrez comment [configurer des en-têtes d'e-mails.](https://developers.hubspot.fr/docs/api-reference/crm-emails-v3/guide.md#set-email-headers) | Pour en savoir plus sur la création par lots d'engagements par e-mails, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-emails-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fcreate). ### Propriétés en lecture seule Certaines propriétés d'e-mail sont également en lecture seule et sont automatiquement renseignées par HubSpot. Les propriétés du tableau ci-dessous sont toutes automatiquement renseignées à partir de la valeur `hs_email_headers`. | Champ | Description | | - | - | | `hs_email_from_email` | L'adresse e-mail de l'expéditeur de l'e-mail. | | `hs_email_from_firstname` | Le prénom de l'expéditeur de l'e-mail. | | `hs_email_from_lastname` | Le nom de famille de l'expéditeur de l'e-mail. | | `hs_email_to_email` | Les adresses e-mail des destinataires de l'e-mail. | | `hs_email_to_firstname` | Les prénoms des destinataires de l'e-mail. | | `hs_email_to_lastname` | Les noms de famille des destinataires de l'e-mail. | > [!WARNING] > > **Remarque :** lors de la récupération d'un en-tête d'e-mail, vous pouvez remarquer que des valeurs existent pour `From` et `Sender`. Ce sont souvent les mêmes, mais comme `Sender` identifie l'élément qui a soumis un e-mail, il existe des scénarios où les valeurs peuvent être différentes. Par exemple, si un e-mail est envoyé à partir d'un alias d'e-mail, la valeur `From` fera référence à l'adresse e-mail réelle de l'utilisateur et la valeur `Sender` fera référence à l'alias d'e-mail. ### Définir des en-têtes d'e-mail Étant donné que les en-têtes remplissent automatiquement les propriétés en lecture seule, il peut être préférable de définir les en-têtes d'e-mail manuellement. Pour définir la valeur `hs_email_headers`, vous pouvez utiliser une chaîne d'échappement JSON avec les données suivantes : ```json theme={null} //Example data { "from": { "email": "from@domain.com", "firstName": "FromFirst", "lastName": "FromLast" }, "to": [ { "email": "ToFirst ToLast", "firstName": "ToFirst", "lastName": "ToLast" } ], "cc": [], "bcc": [] } ``` Par exemple, votre requête de création d'un e-mail peut ressembler à ceci : ```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\":[]}" } } ``` ### Associations Pour créer et associer un e-mail à des fiches d'informations existantes, incluez un objet d'association dans votre requête. Par exemple, pour créer un e-mail et l'associer à une transaction et à un contact, votre corps de requête peut ressembler à ce qui suit : ```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 } ] } ] } ``` Dans l'objet d'association, vous devez ajouter les éléments suivants : | Champ | Description | | - | - | | `to` | La fiche d'informations à laquelle vous souhaitez associer l'e-mail, en fonction de sa valeur unique `id`. | | `types` | Le type d'association entre l'e-mail et la fiche d'informations. Inclut la `associationCategory` et le `associationTypeId`. Les ID de types d'association par défaut sont répertoriés [ici](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md#association-type-id-values), ou vous pouvez récupérer la valeur des types d'associations personnalisés (c'est-à-dire les libellés) via l'[API des associations](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md#retrieve-association-types). | ## Récupérer des e-mails Vous pouvez récupérer des e-mails individuellement ou en lot. Pour en savoir plus sur la récupération des lots, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-emails-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fread). Pour récupérer un e-mail individuel par son ID d'e-mail, effectuez une requête `GET` à `/crm/v3/objects/emails/{emailId}`. Vous pouvez aussi inclure les paramètres suivants dans l'URL de la requête : | Paramètre | Description | | - | - | | `properties` | Une liste séparée par des virgules des propriétés à renvoyer. | | `associations` | Une liste séparée par des virgules des types d'objets pour lesquels récupérer les ID associés. Les associations spécifiées qui n'existent pas ne seront pas renvoyées dans la réponse. Découvrez-en davantage sur l'[API des associations.](https://developers.hubspot.fr/docs/api-reference/crm-associations-v4/guide.md) | Pour demander une liste de tous les e-mails, effectuez une requête `GET` à `crm/v3/objects/emails`. Vous pouvez inclure les paramètres suivants dans l'URL de la requête : | Paramètre | Description | | - | - | | `limit` | Le nombre maximum de résultats à afficher par page. | | `properties` | Une liste séparée par des virgules des propriétés à renvoyer. | ## Mettre à jour les e-mails Vous pouvez mettre à jour des e-mails individuellement ou par lots. Pour mettre à jour un e-mail individuel avec son ID d'e-mail, effectuez une requête `PATCH` à `/crm/v3/objects/emails/{emailId}`. Dans le corps de la requête, incluez les propriétés d'e-mail que vous souhaitez mettre à jour. Par exemple, votre corps de requête peut ressembler aux éléments suivants : ```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!" } } ``` HubSpot ignorera les valeurs des propriétés inexistantes ou en lecture seule. Pour effacer une valeur de propriété, passez une chaîne vide comme valeur de propriété dans le corps de la requête. Pour en savoir plus sur la mise à jour par lots, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-emails-v3/guide.md#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fupdate). ### Associer des e-mails existants à des fiches d'informations Pour associer un e-mail à des fiches d'informations, comme un contact et ses entreprises associées, effectuez une requête `PUT` à `/crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`. L'URL de la requête contient les champs suivants : | Champ | Description | | - | - | | `emailId` | L'ID de l'e-mail. | | `toObjectType` | Le type d'objet auquel vous souhaitez associer l'e-mail (par exemple, contact ou entreprise) | | `toObjectId` | L'ID de la fiche d'informations avec laquelle vous souhaitez associer l'e-mail. | | `associationTypeId` | Un identifiant unique pour indiquer le type d'association entre l'e-mail et l'autre objet. L'ID peut être représenté numériquement ou en snake case (ex : `email_to_contact`). Vous pouvez récupérer la valeur via l'[API des associations](https://developers.hubspot.fr/docs/api-reference/crm-associations-v3/guide.md). | Par exemple, l'URL de votre requête peut ressembler à ce qui suit : `https://api.hubspot.com/crm/v3/objects/emails/17691787884/associations/contact/104901/198` ### Supprimer une association Pour supprimer une association entre un e-mail et une fiche d'informations, faites une requête `DELETE` à la même URL que ci-dessus : `/crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}` ## Épingler un e-mail sur une fiche d'informations Vous pouvez [épingler un e-mail](https://knowledge.hubspot.com/fr/records/pin-an-activity-on-a-record) sur une fiche d'informations afin qu'il reste en haut de la chronologie de la fiche d'informations. L'e-mail doit déjà être associé à la fiche d'informations avant d'être épinglé, et vous ne pouvez épingler qu'une seule activité par fiches d'informations. Pour épingler un e-mail, incluez l'`id` de l'e-mail dans le champ `hs_pinned_engagement_id` lors de la création ou de la mise à jour d'une fiche d'informations via les API objet. Découvrez-en davantage sur l'utilisation des API d'[entreprises](https://developers.hubspot.fr/docs/api-reference/crm-companies-v3/guide.md#pin-an-activity-on-a-company-record)[, de contacts](https://developers.hubspot.fr/docs/api-reference/crm-contacts-v3/guide.md#pin-an-activity-on-a-contact-record), de [transactions](https://developers.hubspot.fr/docs/api-reference/crm-deals-v3/guide.md#pin-an-activity-on-a-deal-record), de [tickets](https://developers.hubspot.fr/docs/api-reference/crm-tickets-v3/guide.md#pin-an-activity-on-a-ticket-record) et d'[objets personnalisés](https://developers.hubspot.fr/docs/api-reference/crm-custom-objects-v3/guide.md). ## Supprimer des e-mails Lorsque vous supprimez un e-mail, il est définitivement supprimé et ne peut pas être restauré. Vous pouvez supprimer des e-mails individuellement ou par lots. Pour mettre à jour un e-mail individuel avec son ID d'e-mail, effectuez une requête `DELETE` à `/crm/v3/objects/emails/{emailId}`. Pour en savoir plus sur la suppression des e-mails, consultez la [documentation de référence](https://developers.hubspot.fr/docs/api-reference/crm-emails-v3/guide.md#delete-%2Fcrm%2Fv3%2Fobjects%2Femails%2F%7Bemailid%7D).