Letzte Änderung: 22. August 2025

Run in Postman

 Verwenden Sie die E-Mail-Interaktionen-API, um E-Mails in CRM-Datensätzen zu protokollieren und zu verwalten. Sie können E-Mail-Aktivitäten entweder in HubSpot oder über die E-Mails-API protokollieren. Im Folgenden erfahren Sie, wie Sie E-Mails über die API verwalten können. Mehr über das Anzeigen aller verfügbaren Endpunkte und deren Anforderungen finden Sie in der Referenzdokumentation.

​
Eine E-Mail erstellen

Um eine E-Mail-Interaktion zu erstellen, führen Sie eine POST-Anfrage an /crm/v3/objects/emails durch. Fügen Sie im Anfragetext E-Mail-Details in einem properties-Objekt hinzu. Sie können auch ein associations-Objekt hinzufügen, um Ihre neue E-Mail einem vorhandenen Datensatz (z. B. Kontakten, Unternehmen) zuzuordnen.

​
Eigenschaften

Im properties-Objekt können Sie die folgenden Felder einschließen:
FeldBeschreibung
hs_timestampErforderlich. Dieses Feld markiert den Zeitpunkt der Erstellung der E-Mail und bestimmt, wo Sie die E-Mail in der Datensatzchronik finden. Sie können entweder einen Unix-Zeitstempel im Millisekunden- oder UTC-Format verwenden.
hubspot_owner_idDie ID des zuständigen Mitarbeiters, der der E-Mail zugeordnet ist. Dieses Feld bestimmt den Benutzer, der in der Datensatzchronik als E-Mail-Ersteller aufgeführt ist.
hs_email_directionDie Richtung, in der die E-Mail gesendet wurde Mögliche Werte sind: EMAIL: Die E-Mail wurde vom CRM aus gesendet oder wurde gesendet und mit der BCC-Adresse beim CRM protokolliert. INCOMING_EMAIL: Die E-Mail war eine Antwort auf eine protokollierte ausgehende E-Mail. FORWARDED_EMAIL: Die E-Mail wurde an das CRM weitergeleitet.
hs_email_htmlDer Text einer E-Mail, wenn sie von einem CRM-Datensatz gesendet wird.
hs_email_statusDer Sendestatus der E-Mail. Der Wert kann BOUNCED, FAILED, SCHEDULED, SENDING oder SENT sein.
hs_email_subjectDie Betreffzeile der protokollierten E-Mail.
hs_email_textDer Text der E-Mail.
hs_attachment_idsDie IDs der Anhänge der E-Mail. Mehrere Anhang-IDs sind durch ein Semikolon getrennt.
hs_email_headersDie Header der E-Mail. Der Wert für diese Eigenschaft wird automatisch in bestimmte schreibgeschützte E-Mail-Eigenschaften übernommen. Erfahren Sie, wie Sie E-Mail-Header festlegen.
Weitere Informationen zur Batch-Erstellung von E-Mail-Interaktionen finden Sie in der Referenzdokumentation.

​
Schreibgeschützte Eigenschaften

Es gibt auch einige schreibgeschützte E-Mail-Eigenschaften, die automatisch von HubSpot ausgefüllt werden. Die Eigenschaften in der folgenden Tabelle werden alle automatisch vom hs_email_headers-Wert übernommen.
FeldBeschreibung
hs_email_from_emailDie E-Mail-Adresse des Absenders der E-Mail
hs_email_from_firstnameDer Vorname des E-Mail-Absenders
hs_email_from_lastnameDer Nachname des E-Mail-Absenders
hs_email_to_emailDie E-Mail-Adressen der Empfänger der E-Mail
hs_email_to_firstnameDie Vornamen der Empfänger der E-Mail
hs_email_to_lastnameDie Nachnamen der Empfänger der E-Mail
Hinweis: Wenn Sie einen E-Mail-Header abrufen, stellen Sie möglicherweise fest, dass sowohl für From als auch Sender Werte vorhanden sind. Diese sind oft identisch, aber da Sender identifiziert, durch was eine E-Mail tatsächlich gesendet wurde, gibt es Szenarien, in denen die Werte abweichen können. Wird beispielsweise eine E-Mail von einem E-Mail-Alias gesendet, bezieht sich der From-Wert auf die tatsächliche E-Mail-Adresse des Benutzers und der Sender-Wert auf den E-Mail-Alias.

​
E-Mail-Header festlegen

Da die schreibgeschützten Eigenschaften automatisch mit Headern ausgefüllt werden, sollten Sie die E-Mail-Header manuell festlegen. Um den hs_email_headers-Wert festzulegen, können Sie eine mit JSON-Escape-Zeichen versehene Zeichenfolge mit den folgenden Daten verwenden: 
//Example data
{
  "from": {
    "email": "from@domain.com",
    "firstName": "FromFirst",
    "lastName": "FromLast"
  },
  "to": [
    {
      "email": "ToFirst ToLast<to@test.com>",
      "firstName": "ToFirst",
      "lastName": "ToLast"
    }
  ],
  "cc": [],
  "bcc": []
}
Ihre Anfrage zum Erstellen einer E-Mail kann beispielsweise so aussehen: 
//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\":[]}"
  }
}

​
Zuordnungen

Um eine E-Mail zu erstellen und bestehenden Datensätzen zuzuordnen, schließen Sie ein associations-Objekt in Ihre Anfrage ein. Um beispielsweise eine E-Mail zu erstellen und sie einem Deal und einem Kontakt zuzuordnen, könnte Ihr Anfragetext wie folgt aussehen: 
// 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
        }
      ]
    }
  ]
}
Im associations-Objekt sollten Sie Folgendes einschließen:
FeldBeschreibung
toDer Datensatz, den Sie der E-Mail zuordnen möchten, angegeben durch ihren eindeutigen id-Wert.
typesDer Typ der Zuordnung zwischen E-Mail und Datensatz. Beziehen Sie die associationCategory und associationTypeId ein. Standardzuordnungstyp-IDs sind hier aufgeführt. Sie können den Wert für benutzerdefinierte Zuordnungstypen (d. h. Label) über die Zuordnungen-API abrufen.

​
E-Mails abrufen

Sie können E-Mails einzeln oder mehrere gleichzeitig (batchweise) abrufen. Weitere Informationen zum Batch-Abruf finden Sie in der Referenzdokumentation. Um eine einzelne E-Mail anhand ihrer E-Mail-ID abzurufen, führen Sie eine GET-Anfrage an /crm/v3/objects/emails/{emailId} durch. Sie können auch die folgenden Parameter in der Anfrage-URL berücksichtigen:
ParameterBeschreibung
propertiesEine durch Kommas getrennte Liste der Eigenschaften, die zurückgegeben werden sollen.
associationsEine durch Kommas getrennte Liste von Objekttypen, für die zugehörige IDs abgerufen werden sollen. Alle angegebenen Zuordnungen, die nicht vorhanden sind, werden nicht in der Antwort zurückgegeben. Erfahren Sie mehr über die Zuordnungen-API.
Um eine Liste aller E-Mails anzufordern, führen Sie eine GET-Anfrage an crm/v3/objects/emails durch. Sie können die folgenden Parameter in der Anfrage-URL berücksichtigen:
ParameterBeschreibung
limitDie maximale Anzahl an Ergebnissen, die pro Seite angezeigt werden können.
propertiesEine durch Kommas getrennte Liste der Eigenschaften, die zurückgegeben werden sollen.

​
E-Mails aktualisieren

Sie können E-Mails einzeln oder mehrere gleichzeitig (batchweise) aktualisieren. Um eine einzelne E-Mail anhand ihrer E-Mail-ID zu aktualisieren, führen Sie eine PATCH-Anfrage an /crm/v3/objects/emails/{emailId} durch. Fügen Sie im Anfragetext die E-Mail-Eigenschaften ein, die Sie aktualisieren möchten. Ihr Anfragetext kann beispielsweise wie folgt aussehen: 
// 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 ignoriert Werte für schreibgeschützte und nicht vorhandene Eigenschaften. Um einen Eigenschaftswert zu löschen, übergeben Sie eine leere Zeichenfolge für die Eigenschaft im Anfragetext. Weitere Informationen zur Batch-Aktualisierung finden Sie in der Referenzdokumentation.

​
Vorhandene E-Mails zu Datensätzen zuordnen

Um eine E-Mail Datensätzen zuzuordnen, z. B. einem Kontakt und seinen zugeordneten Unternehmen, führen Sie eine PUT-Anfrage an /crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} durch. Die Anfrage-URL enthält die folgenden Felder:
FeldBeschreibung
emailIdDie ID der E-Mail
toObjectTypeDer Typ des Objekts, dem Sie die E-Mail zuordnen möchten (z. B. Kontakt oder Unternehmen)
toObjectIdDie ID des Datensatzes, dem Sie die E-Mail zuordnen möchten
associationTypeIdEine eindeutige ID, die den Zuordnungstyp zwischen der E-Mail und dem anderen Objekt angibt. Die ID kann numerisch oder in Snake-Case (z. B. email_to_contact) dargestellt werden. Sie können den Wert über die Zuordnungen-API abrufen.
Ihre Anfrage-URL könnte beispielsweise wie folgt aussehen: https://api.hubspot.com/crm/v3/objects/emails/17691787884/associations/contact/104901/198

​
Eine Zuordnung entfernen

Um eine Zuordnung zwischen einer E-Mail und einem Datensatz zu entfernen, führen Sie eine DELETE-Anfrage an die gleiche URL wie oben durch: /crm/v3/objects/emails/{emailId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

​
Eine E-Mail an einen Datensatz anpinnen

Sie können eine E-Mail an einen Datensatz anpinnen, sodass sie oben in der Chronik des Datensatzes bleibt. Die E-Mail muss bereits vor dem Anpinnen dem Datensatz zugeordnet sein, und Sie können nur eine Aktivität pro Datensatz anpinnen. Um eine E-Mail anzupinnen, berücksichtigen Sie die id der E-Mail im hs_pinned_engagement_id-Feld, wenn Sie einen Datensatz über die Objekt-APIs erstellen oder aktualisieren. Erfahren Sie mehr über das Verwenden der Unternehmen-, Kontakte-, Deals-, Tickets- und Benutzerdefinierte Objekte-APIs.

​
E-Mails löschen

Wenn Sie eine E-Mail löschen, wird sie vollständig gelöscht und kann nicht wiederhergestellt werden. Sie können E-Mails einzeln oder mehrere gleichzeitig (batchweise) löschen. Um eine einzelne E-Mail anhand ihrer E-Mail-ID zu löschen, führen Sie eine DELETE-Anfrage an /crm/v3/objects/emails/{emailId} durch. Weitere Informationen zum Löschen von E-Mails finden Sie in der Referenzdokumentation.