Interacciones | Correos electrónicos

Run in Postman

Requisitos de ámbito

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:

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 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.`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_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.

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.

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:

//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 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\":\"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\":[]}"
  }
}

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:

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, 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á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.

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:

// 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:

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.

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.

Cuenta y configuración

Gestión de aplicaciones

Autenticación

Automatización

CMS

Preferencias de comunicación

Conversaciones

CRM

Eventos

Archivos

Marketing

Programador

Webhooks

Interacciones | Correos electrónicos

Run in Postman

Crear un correo electrónico

Propiedades

Propiedades de solo lectura

Definir encabezados de correo electrónico

Asociaciones

Obtener correos electrónicos

Actualizar correos electrónicos

Asociar correos electrónicos existentes con registros

Eliminar una asociación

Fijar un correo electrónico a un registro

Eliminar correos electrónicos

Run in Postman

​Crear un correo electrónico

​Propiedades

​Propiedades de solo lectura

​Definir encabezados de correo electrónico

​Asociaciones

​Obtener correos electrónicos

​Actualizar correos electrónicos

​Asociar correos electrónicos existentes con registros

​Eliminar una asociación

​Fijar un correo electrónico a un registro

​Eliminar correos electrónicos

Crear un correo electrónico

Propiedades

Propiedades de solo lectura

Definir encabezados de correo electrónico

Asociaciones

Obtener correos electrónicos

Actualizar correos electrónicos

Asociar correos electrónicos existentes con registros

Eliminar una asociación

Fijar un correo electrónico a un registro

Eliminar correos electrónicos