Saltar al contenido principal

Run in Postman
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 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.

​
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:
CampoDescripción
hs_timestampObligatorio. 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_idEl ID del propietario 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_directionLa 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.INCOMING_EMAIL: el correo electrónico era una respuesta a un correo saliente registrado. FORWARDED_EMAIL: el correo electrónico se reenvió al CRM.
hs_email_htmlEl cuerpo de un correo electrónico si se envía desde un registro del CRM.
hs_email_statusEl estado de envío del correo El valor puede ser BOUNCED, FAILED, SCHEDULED, SENDING o SENT.
hs_email_subjectLa línea de asunto del correo electrónico registrado.
hs_email_textEl cuerpo del correo electrónico.
hs_attachment_idsLos 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_headersLos 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.
Obtén más información sobre la creación de interacciones por correo electrónico por lotes consultando esta documentación de referencia.

​
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.
CampoDescripción
hs_email_from_emailLa dirección de correo electrónico del remitente.
hs_email_from_firstnameEl nombre del remitente del correo electrónico.
hs_email_from_lastnameLos apellidos del remitente del correo electrónico.
hs_email_to_emailLas direcciones de correo electrónico de los destinatarios del correo electrónico.
hs_email_to_firstnameLos nombres de los destinatarios del correo electrónico.
hs_email_to_lastnameLos 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: 
//Example data
{
  "from": {
    "email": "[email protected]",
    "firstName": "FromFirst",
    "lastName": "FromLast"
  },
  "to": [
    {
      "email": "ToFirst ToLast<[email protected]>",
      "firstName": "ToFirst",
      "lastName": "ToLast"
    }
  ],
  "cc": [],
  "bcc": []
}
Por ejemplo, tu solicitud para crear un correo electrónico puede verse así: 
//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\":\"[email protected]\",\"firstName\":\"FromFirst\",\"lastName\":\"FromLast\"},\"sender\":{\"email\":\"[email protected]\",\"firstName\":\"SenderFirst\",\"lastName\":\"SenderLast\"},\"to\":[{\"email\":\"ToFirst+ToLast<[email protected]>\",\"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: 
// 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:
CampoDescripción
toEl registro que quieres asociar con el correo electrónico, especificado por su valor único id.
typesEl 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, 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.

​
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. 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ámetroDescripción
propertiesUna lista separada por comas de las propiedades que se devolverán.
associationsUna 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.
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ámetroDescripción
limitEl número máximo de resultados que se mostrarán por página.
propertiesUna 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: 
// 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.

​
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:
CampoDescripción
emailIdEl ID del correo electrónico.
toObjectTypeEl tipo de objeto con el que quieres asociar el correo electrónico (por ejemplo, contacto o empresa)
toObjectIdEl ID del registro con el que quieres asociar el correo electrónico.
associationTypeIdUn 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.
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 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, contactos, negocios, tickets y objetos personalizados.

​
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.
Last modified on December 10, 2025