> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Interacciones | Correos electrónicos
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Esta API requiere uno de los siguientes ámbitos:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
Usa la API de interacción de correo electrónico para registrar y gestionar correos en los registros del CRM. Puedes registrar las actividades de correo electrónico [en HubSpot](https://knowledge.hubspot.com/es/records/manually-log-activities-on-records) o a través de la API de correos electrónicos.
En este artículo explicamos los métodos básicos de gestión de correos electrónicos a través de la API. Para ver todos los endpoints disponibles y sus requisitos, consulta [esta documentación de referencia](/api-reference/crm-emails-v3/guide).
## Crear un correo electrónico
Para crear una interacción de correo electrónico, haz una solicitud `POST` a `/crm/v3/objects/emails`.
En el cuerpo de la solicitud, agrega los detalles del correo electrónico en un objeto **propiedades**. También puedes agregar el objeto **asociaciones** para asociar tu nuevo correo electrónico con un registro existente (por ejemplo, contactos, empresas).
### Propiedades
En el objeto propiedades, puedes incluir los siguientes campos:
| Campo | Descripción |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hs_timestamp` | Obligatorio. Este campo marca la hora de creación del correo electrónico y determina dónde se encuentra el correo en la cronología del registro. Puedes usar una marca de tiempo Unix en milisegundos o en formato UTC. |
| `hubspot_owner_id` | El [ID del propietario](/api-reference/crm-crm-owners-v3/guide) asociado con el correo electrónico. Este campo determina el usuario que aparece como creador del correo electrónico en la cronología del registro. |
| `hs_email_direction` | La dirección con la que se envió en el correo Los valores posibles incluyen: `EMAIL`: el correo electrónico se envió desde el CRM o se envió y se registró en el CRM con la [dirección CCO.](https://knowledge.hubspot.com/es/connected-email/log-email-in-your-crm-with-the-bcc-or-forwarding-address)`INCOMING_EMAIL`: el correo electrónico era una respuesta a un correo saliente registrado. `FORWARDED_EMAIL`: el correo electrónico se [reenvió al CRM](https://knowledge.hubspot.com/es/connected-email/log-email-in-your-crm-with-the-bcc-or-forwarding-address). |
| `hs_email_html` | El cuerpo de un correo electrónico si se envía desde un registro del CRM. |
| `hs_email_status` | El estado de envío del correo El valor puede ser `BOUNCED`, `FAILED`, `SCHEDULED`, `SENDING` o `SENT`. |
| `hs_email_subject` | La línea de asunto del correo electrónico registrado. |
| `hs_email_text` | El cuerpo del correo electrónico. |
| `hs_attachment_ids` | Los ID de los archivos adjuntos al correo electrónico. Los ID de varios archivos adjuntos están separados por un punto y coma. |
| `hs_email_headers` | Los encabezados del correo electrónico. El valor de esta propiedad rellenará automáticamente ciertas propiedades de correo electrónico de solo lectura. Aprende a [configurar encabezados de correo electrónico.](/api-reference/crm-emails-v3/guide#set-email-headers) |
Obtén más información sobre la creación de interacciones por correo electrónico por lotes consultando [esta documentación de referencia](/api-reference/crm-emails-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fcreate).
### Propiedades de solo lectura
También hay algunas propiedades de correo electrónico que son de solo lectura, y que HubSpot rellena automáticamente. Las propiedades de la tabla siguiente se rellenan automáticamente a partir del valor `hs_email_headers`.
| Campo | Descripción |
| ------------------------- | ---------------------------------------------------------------------------------- |
| `hs_email_from_email` | La dirección de correo electrónico del remitente. |
| `hs_email_from_firstname` | El nombre del remitente del correo electrónico. |
| `hs_email_from_lastname` | Los apellidos del remitente del correo electrónico. |
| `hs_email_to_email` | Las direcciones de correo electrónico de los destinatarios del correo electrónico. |
| `hs_email_to_firstname` | Los nombres de los destinatarios del correo electrónico. |
| `hs_email_to_lastname` | Los apellidos del destinatario del correo electrónico. |
**Nota:** Al obtener un encabezado de correo electrónico, puede que haya valores tanto para `From` como para `Sender`. Suelen ser los mismos, pero como `Sender` identifica la entidad que realmente envió un correo electrónico, hay escenarios en los que los valores pueden diferir. Por ejemplo, si se envía un correo electrónico desde un alias de correo electrónico, el valor `From` hará referencia a la dirección de correo electrónico real del usuario y el valor `Sender` al alias de correo.
### Definir encabezados de correo electrónico
Dado que los encabezados rellenan automáticamente las propiedades de solo lectura, es posible que quieras definir manualmente los encabezados de correo electrónico. Para definir el valor `hs_email_headers`, puedes usar una cadena de escape JSON con los siguientes datos:
```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 ejemplo, tu solicitud para crear un correo electrónico puede verse así:
```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\":[]}"
}
}
```
### Asociaciones
Para crear y asociar un correo electrónico con registros existentes, incluye el objeto asociaciones en tu solicitud. Por ejemplo, para crear un correo electrónico y asociarlo con un negocio y un contacto, el cuerpo de tu solicitud podría verse de la siguiente manera:
```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
}
]
}
]
}
```
En el objeto asociaciones, debes incluir lo siguiente:
| Campo | Descripción |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | El registro que quieres asociar con el correo electrónico, especificado por su valor único `id`. |
| `types` | El tipo de asociación entre el correo electrónico y el registro. Incluye `associationCategory` y `associationTypeId`. Los ID de los tipos de asociación predeterminados se enumeran en [este recurso](/api-reference/crm-associations-v4/guide#association-type-id-values), y también puedes obtener el valor de los tipos de asociación personalizados (es decir, etiquetas) a través de la [API de asociaciones](/api-reference/crm-associations-v4/guide#retrieve-association-types). |
## Obtener correos electrónicos
Puedes obtener correos electrónicos individualmente o en bloque. Obtén más información sobre la obtención de lotes consultando [esta documentación de referencia](/api-reference/crm-emails-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fread).
Para obtener un correo electrónico individual por su ID de correo electrónico, haz una solicitud `GET` a `/crm/v3/objects/emails/{emailId}`. También puedes incluir los siguientes parámetros en la URL de la solicitud:
| Parámetro | Descripción |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | Una lista separada por comas de las propiedades que se devolverán. |
| `associations` | Una lista separada por comas de los tipos de objetos para obtener los ID asociados. En la respuesta no aparecerán las asociaciones especificadas que no existan. Más información sobre la [API de asociaciones.](/api-reference/crm-associations-v4/guide) |
Para solicitar una lista de todos los correos electrónicos, envía una solicitud `GET` a `crm/v3/objects/emails`. Puedes incluir los siguientes parámetros en la URL de la solicitud:
| Parámetro | Descripción |
| ------------ | ------------------------------------------------------------------ |
| `limit` | El número máximo de resultados que se mostrarán por página. |
| `properties` | Una lista separada por comas de las propiedades que se devolverán. |
## Actualizar correos electrónicos
Puedes actualizar los correos electrónicos individualmente o en bloque. Para actualizar un correo electrónico individual por su ID de correo, haz una solicitud `PATCH` a `/crm/v3/objects/emails/{emailId}`.
En el cuerpo de la solicitud, incluye las propiedades de correo electrónico que quieres actualizar. Por ejemplo, el cuerpo de la solicitud puede tener un aspecto similar al siguiente:
```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 ignorará los valores de las propiedades de solo lectura e inexistentes. Para borrar el valor de una propiedad, pasa una cadena vacía para esa propiedad en el cuerpo de la solicitud.
Obtén más información sobre la actualización en bloques consultando [esta documentación de referencia](/api-reference/crm-emails-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Femails%2Fbatch%2Fupdate).
### Asociar correos electrónicos existentes con registros
Para asociar un correo electrónico con registros, como un contacto y sus empresas asociadas, haz una solicitud `PUT` a `/crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`. La URL de la solicitud contiene los siguientes campos:
| Campo | Descripción |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `emailId` | El ID del correo electrónico. |
| `toObjectType` | El tipo de objeto con el que quieres asociar el correo electrónico (por ejemplo, contacto o empresa) |
| `toObjectId` | El ID del registro con el que quieres asociar el correo electrónico. |
| `associationTypeId` | Un identificador único para indicar el tipo de asociación entre el correo electrónico y el otro objeto. El ID se puede representar numéricamente o con palabras separadas por guion bajo (por ejemplo, `email_to_contact`). Puedes obtener el valor a través de la [API de asociaciones](/api-reference/crm-associations-v3/guide). |
Por ejemplo, la URL de tu solicitud puede tener un aspecto similar al siguiente:
`https://api.hubspot.com/crm/v3/objects/emails/17691787884/associations/contact/104901/198`
### Eliminar una asociación
Para eliminar una asociación entre un correo electrónico y un registro, haz una solicitud `DELETE` en la misma URL que la de arriba:
`/crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`
## Fijar un correo electrónico a un registro
Puedes [fijar un correo electrónico](https://knowledge.hubspot.com/es/records/pin-an-activity-on-a-record) a un registro para que permanezca en la parte superior de la cronología del registro. El correo electrónico ya debe estar asociado con el registro antes de fijarlo, y solo puedes fijar una actividad por registro. Para fijar un correo electrónico, incluye el `id` del correo electrónico en el campo `hs_pinned_engagement_id` al crear o actualizar un registro a través de las API de objetos. Obtén más información sobre el uso de las API de [empresas](/api-reference/crm-companies-v3/guide#pin-an-activity-on-a-company-record)[, contactos](/api-reference/crm-contacts-v3/guide#pin-an-activity-on-a-contact-record), [negocios](/api-reference/crm-deals-v3/guide#pin-an-activity-on-a-deal-record), [tickets](/api-reference/crm-tickets-v3/guide#pin-an-activity-on-a-ticket-record) y [objetos personalizados](/api-reference/crm-custom-objects-v3/guide).
## Eliminar correos electrónicos
Cuando eliminas un correo electrónico, este se elimina permanentemente y no se puede restaurar. Puedes eliminar correos electrónicos individualmente o en bloque.
Para eliminar un correo electrónico individual por su ID de correo electrónico, haz una solicitud `DELETE` a `/crm/v3/objects/emails/{emailId}`.
Obtén más información sobre cómo eliminar correos electrónicos consultando [esta documentación de referencia](/api-reference/crm-emails-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Femails%2F%7Bemailid%7D).