Transaktions-E-Mails

ÜberblickEndpunkte

Mit dem transaktionalen E-Mail-Add-on können Sie E-Mails für Geschäftsbelege, Kontoaktualisierungen, Änderungen der Allgemeinen Geschäftsbedingungen und andere wichtige Geschäftsvorgänge über eine dedizierte IP-Adresse senden.

Transaktions-E-Mails sind für beziehungsbasierte Interaktionen gedacht, im Gegensatz zu Marketing-E-Mails, die typischerweise zur Bewerbung von Inhalten verwendet werden.

Methoden zum Senden von Transaktions-E-Mails 

Es gibt drei Möglichkeiten, Transaktions-E-Mails zu implementieren:

Methode Überblick Anwendungsfall als Beispiel
Transaktions-E-Mail innerhalb der App Erstellen Sie Transaktions-E-Mails mithilfe des E-Mail-Editors von HubSpot.

Sie erhalten die gleichen Vorteile wie bei HubSpot-Standard-E-Mails, z. B. Smart Content, Personalisierung und Vorlagen.

Erfahren Sie mehr über das Einrichten von Transaktions-E-Mail innerhalb der App.		 Senden Sie eine E-Mail zu einer Richtlinienaktualisierung an Ihre Kunden mit einem Link zu einer neuen Richtlinie. Da es sich um ein Service-Update und nicht um eine Marketing-E-Mail handelt, müssen Sie keine Abonnementlinks (z. B. CAN-SPAM-Links) einfügen. Sie müssen keine benutzerdefinierten Eigenschaften oder Informationen aus externen Systemen verwenden.
SMTP-API
Senden Sie Transaktions-E-Mails über Ihre eigene Website oder App, während Sie die E-Mail-Performance verfolgen und Kontaktinformationen in HubSpot erstellen. Die optionale Möglichkeit, Kontaktinformationen zu erstellen, basiert auf der Erstellung des SMTP-Tokens.

Weitere Informationen finden Sie im Abschnitt „SMTP-API“ weiter unten.

 Senden Sie eine E-Mail zur Bestätigung der Account-Anmeldung über ein separates transaktionsbezogene E-Mail-System, während Sie die E-Mail-Performance verfolgen und Kontakte in HubSpot erstellen.
Single-Send-API Eine Kombination aus Transaktions-E-Mail innerhalb der App und SMTP-API.

Erstellen Sie Transaktions-E-Mails mit dem E-Mail-Editor von HubSpot und fügen Sie benutzerdefinierte externe Token zu Ihrer E-Mail hinzu, die Sie über die API an HubSpot senden können.

Weitere Informationen finden Sie im Abschnitt „Single-Send-API“ weiter unten.		 Senden Sie eine Kaufbeleg-E-Mail an Ihren Kunden mit HubSpot. Die E-Mail wird ausgelöst, wenn der Kauf getätigt wird und benutzerdefinierte Werte aus einem anderen System übertragen werden (z. B. gekaufte Artikel und Kaufbetrag). Sie können außerdem die Performance dieser E-Mail in HubSpot verfolgen.

Please note: any contacts who are CC'd on a transactional email will not be tracked and the email will not appear on the record timeline of the CC'd contact.

SMTP-API

Eine Transaktions-E-Mail, die über die SMTP-API gesendet wird, wird automatisch von spezifischen Kriterien ausgelöst, z. B. beim Kauf auf einer E-Commerce-Website. Diese API kann in beliebige interne Systeme oder Systeme von Dritten integriert werden, um die E-Mail auszulösen und Daten außerhalb von HubSpot zu verknüpfen (z. B. Versandinformationen oder Kaufpreis). Die E-Mail wird von Ihrem System gesendet, ist jedoch mit den HubSpot-Trackingcodes verknüpft, die eine vollständige Verfolgung und Messung der Interaktionen ermöglichen.

Um eine E-Mail mit der SMTP-API zu senden, müssen Sie ein SMTP-API-Token verwenden, um Anmeldeinformationen für den HubSpot SMTP-Server zu erhalten. Nach der Anmeldung beim Server können Sie die E-Mail über SMTP senden. Wenn Sie keine SMTP-API-Token erstellt haben, müssen Sie zuerst ein neues Token generieren. Wenn Sie bereits SMTP-API-Token erstellt haben, informieren Sie sich über die verschiedenen Methoden zum Erstellen Ihrer Token über die API. Nachdem Sie Ihr Token abgerufen haben, informieren Sie sich über die Anmeldung beim HubSpot SMTP-Server.

Alle Domains, die Sie als Absenderadresse Ihrer E-Mails verwenden, müssen als E-Mail-Domain in HubSpot verknüpft werden. Ein Fehler tritt auf, wenn Sie Transaktions-E-Mails über die SMTP-API mithilfe einer Domain senden, die nicht für Ihren HubSpot-Account autorisiert ist.

Please note: all methods in the SMTP API require an OAuth token for authentication.

If you prefer, all of the methods below for creating, retrieving, deleting, and resetting passwords for SMTP API tokens can be done within your HubSpot account, rather than the API.

Neues SMTP-API-Token erstellen

Um ein neues SMTP-API-Token zu erstellen, stellen Sie eine POST-Anfrage an /marketing/v3/transactional/smtp-tokens/.

Der Anfragetext muss ein JSON-formatiertes Objekt mit den folgenden Eigenschaften sein:

  • createContact: gibt an, ob ein Kontakt für E-Mail-Empfänger erstellt werden soll.
  • campaignName: ein Name für die Kampagne, die dem SMTP-API-Token zugeordnet ist.

Die Antwort enthält ein SMTP-Token-Objekt, das Folgendes enthält:

  • id: Benutzername, um sich am HubSpot SMTP-Server anzumelden.
  • createdBy: E-Mail-Adresse des Benutzers, der die Anfrage zur Erstellung des Tokens gesendet hat.
  • password: Passwort für die Protokollierung im HubSpot SMTP-Server.
  • emailCampaignId: ID, die der in der Anfrage zur Token-Erstellung bereitgestellten Kampagne zugewiesen wurde.
  • createdAt: Zeitstempel, der beim Erstellen eines Tokens generiert wird.
  • createContact: gibt an, ob ein Kontakt für E-Mail-Empfänger erstellt werden soll.
  • campaignName: der Name der Kampagne, die dem Token zugeordnet ist.

Mit Ihrem erstellten Token können Sie sich am HubSpot SMTP-Server mit den Werten id und password anmelden.

Das Passwort eines Tokens kann nur zum Zeitpunkt der Erstellung abgerufen werden. Wenn Sie das Passwort verlieren oder ein neues Passwort festlegen möchten, müssen Sie das Passwort des Tokens zurücksetzen. 

Please note: SMTP API tokens generated through the public API expire after 12 months. Once expired, they're automatically deleted. Tokens created directly within your HubSpot account do not expire automatically.

Vorhandene SMTP-API-Token abrufen

Nachfolgend finden Sie die verfügbaren Methoden zum Erstellen dieser Token mithilfe der API.

SMTP-API-Token nach Kampagne auflisten

Um entweder eine Liste der Token nach Kampagnenname oder ein einzelnes Token nach Kampagnen-ID abzurufen, nehmen Sie eine GET-Anfrage an /marketing/v3/transactional/smtp-tokens vor.

Sie müssen auch einen Parameter campaignName oder emailCampaignId mit der Anfrage hinzufügen. In der Registerkarte „Endpunkte“ am Anfang dieses Artikels Sie finden Sie sämtliche Anfragedetails.

Antwortdetails

Die Antwort umfasst results und paging in den Top-Level-Feldern:

  • results: eine Sammlung von SmtpApiTokenView umfasst:
    • id: Benutzername, um sich am HubSpot SMTP-Server anzumelden.
    • createdBy: E-Mail-Adresse des Benutzers, der die Anfrage zur Erstellung des Tokens gesendet hat.
    • emailCampaignId: ID, die der in der Anfrage zur Token-Erstellung bereitgestellten Kampagne zugewiesen wurde.
    • createdAt: Zeitstempel, der beim Erstellen eines Tokens generiert wird.
    • createContact: gibt an, ob ein Kontakt für E-Mail-Empfänger erstellt werden soll.
    • campaignName: der Name der Kampagne, die dem Token zugeordnet ist.
  • paging: enthält ein next.after-Feld, das zur Anfrage weiterer Ergebnisse verwendet werden kann.

Einzelnes SMTP-API-Token anfragen

Um ein einzelnes SMTP-API-Token nach ID anzufragen, nehmen Sie eine GET-Anfrage an /marketing/v3/transactional/smtp-tokens/{tokenId} vor.

Antwortdetails

Die Antwort enthält SmtpApiTokenView, die Folgendes enthält:

  • id: Benutzername, um sich am HubSpot SMTP-Server anzumelden.
  • createdBy: E-Mail-Adresse des Benutzers, der die Anfrage zur Erstellung des Tokens gesendet hat.
  • emailCampaignId: ID, die der in der Anfrage zur Token-Erstellung bereitgestellten Kampagne zugewiesen wurde.
  • createdAt: Zeitstempel, der beim Erstellen eines Tokens generiert wird.
  • createContact: gibt an, ob ein Kontakt für E-Mail-Empfänger erstellt werden soll.
  • campaignName: der Name der Kampagne, die dem Token zugeordnet ist.

Vorhandene Token verwalten

Nachdem Sie Token erstellt haben, können Sie mit der API ein Passwort zurücksetzen oder das Token löschen.

Passwort zurücksetzen

Um ein Token-Passwort zurückzusetzen, nehmen Sie eine POST-Anfrage an /marketing/v3/transactional/smtp-tokens/{tokenId}/password-reset vor.

Die Antwort enthält SmtpApiTokenView, die Folgendes enthält:

  • id: Benutzername, um sich am HubSpot SMTP-Server anzumelden.
  • createdBy: E-Mail-Adresse des Benutzers, der die Anfrage zur Erstellung des Tokens gesendet hat.
  • emailCampaignId: ID, die der in der Anfrage zur Token-Erstellung bereitgestellten Kampagne zugewiesen wurde.
  • createdAt: Zeitstempel, der beim Erstellen eines Tokens generiert wird.
  • createContact: gibt an, ob ein Kontakt für E-Mail-Empfänger erstellt werden soll.
  • campaignName: der Name der Kampagne, die dem Token zugeordnet ist.

Ein Token löschen

Um ein einzelnes SMTP-API-Token zu löschen, nehmen Sie eine DELETE-Anfrage an /marketing/v3/transactional/smtp-tokens/{tokenId} vor.

Die Antwort enthält keine Inhalte.

Bitte beachten:

Am HubSpot SMTP-Server anmelden

Nachfolgend finden Sie die Details für das Protokollieren des HubSpot SMTP-Servers mit dem Benutzernamen (id) und dem von Ihrem Token bereitgestellten Passwort.

  • SMTP-Hostname:
    • Verwenden Sie außerhalb der EU smtp.hubapi.com als Hostnamen.
    • Verwenden Sie innerhalb der EU smtp-eu1.hubapi.com als Hostnamen.
  • SMTP-Port:
    • Verwenden Sie außerhalb der EU die Ports 587 (für STARTTLS) oder 465 (für TLS).
    • Verwenden Sie innerhalb der EU die Ports 587 oder 25 (für STARTTLS).
  • SMTP-Benutzername: wird im Feld „ID“ angegeben
  • SMTP-Passwort: wird im Feld „Passwort“ angegeben

Single-Send-API

Die Single-Send-API sendet Vorlagen-E-Mails, die im E-Mail-Tool von HubSpot mithilfe einer JSON-formatierten POST-Anfrage erstellt wurden. Alle E-Mails, die über diese API gesendet werden, werden basierend auf der E-Mail-Adresse automatisch mit Kontaktdatensätzen verknüpft. Wenn es keinen Kontakt mit einer übereinstimmenden E-Mail-Adresse gibt, wird ein neuer Kontakt mit dieser E-Mail erstellt. Wenn Sie E-Mails senden möchten, ohne Kontakte zu erstellen, verwenden Sie die SMTP-API.

Richten Sie zunächst Ihre E-Mail in HubSpot ein. Nachdem die E-Mail veröffentlicht wurde, können Sie die Empfängerdetails festlegen, einschließlich beliebiger Kontakt- oder benutzerdefinierter Eigenschaften, die in der E-Mail-Vorlage im Text der API-Anfrage eingerichtet werden. Sie können auch die E-Mail-ID von der E-Mail-Detailseite kopieren. Sie benötigen sie für Ihre Anfrage.

Screenshot 2020-04-15 um 1.00.37 PM

Please note: HubSpot does not save the HTML/JSON sent through this API. You can review the email template from the recipient contact's timeline, but if you want to keep a record of the email's contents, it's recommended to add a BCC to the email.

Um eine E-Mail mit der Single-Send-API zu senden, nehmen Sie eine POST-Anfrage an /marketing/v3/transactional/single-email/send vor.

Die Antwort enthält die folgenden Felder:

    • requestedAt: der Zeitstempel, an dem der Versand angefordert wurde.
  • status: der Status der Versandanfrage. Umfasst PENDING, PROCESSING, CANCELED und COMPLETE.

Eigenschaften anfordern

Der Anfragetext muss ein JSON-formatiertes Objekt mit den folgenden Eigenschaften sein:

  • emailId
  • message
  • contactProperties
  • customProperties

emailId

Das Feld emailId enthält die Content-ID der Transaktions-E-Mail, die im E-Mail-Tool von HubSpot gefunden werden kann.

message

Das Feld „message“ ist ein JSON-Objekt, das alles enthält, was Sie überschreiben möchten. Es muss mindestens das Feld to enthalten sein.

Nachrichten-Objektfelder:

  • to: der Empfänger der E-Mail
  • from: „Von“-Header der E-Mail. Sie können einen Namen in folgendem Format definieren: "from":“Sendername <sender@hubspot.com>"
  • sendId: ID eines bestimmten Versands. Es wird nur eine E-Mail mit einer bestimmten sendId pro Account gesendet. Daher können Sie dieses Feld einfügen, um einen doppelten E-Mail-Versand zu verhindern.
  • replyTo: JSON-Liste mit den „Antwort an“-Headerwerten für die E-Mail.
  • cc: JSON-Liste der E-Mail-Adressen, an die eine Kopie gesendet wird.
  • bcc: JSON-Liste der E-Mail-Adressen, an die eine Blindkopie gesendet wird.

contactProperties

Das Feld contactProperties ist eine JSON-Karte der Kontakteigenschaftswerte. Jeder Kontakteigenschaftswert enthält name und value. Jede Eigenschaft wird im Kontaktdatensatz festgelegt und in der Vorlage angezeigt unter:

name-token-in-template-for-transactional-email

Verwenden Sie diese Eigenschaften, wenn Sie eine Kontakteigenschaft festlegen möchten, während Sie die E-Mail senden. Wenn Sie z. B. einen Beleg senden, sollten Sie eine last_paid_date-Eigenschaft festlegen, da beim Versand des Belegs Informationen über die letzte Zahlung übermittelt werden.

{ "emailId": 4126643121, "message": { "to": "jdoe@hubspot.com" "sendId": "6" }, "contactProperties": { "last_paid_date": "2022-03-01", "firstname": "jane" } }

customProperties

Das customProperties-Feld ist eine JSON-Zuordnung von Schlüssel-Wert-Eigenschaften. Diese Eigenschaften beziehen sich im Allgemeinen auf die E-Mail selbst, nicht auf den Kontakt, der die E-Mail erhält. Sie werden nicht in der Webseitenversion der E-Mail oder in der Ansicht der E-Mail in der Chronik des Kontakts angezeigt. Diese Eigenschaften werden auch nicht in HubSpot gespeichert und sind nur in der gesendeten E-Mail enthalten.

Auf jeden Schlüssel im customProperties-Feld kann in der Vorlage mit einem HubL-Ausdruck für Felder verwiesen werden, die in der custom-Variable enthalten sind (z. B. {{custom.NAME_OF_PROPERTY}}).

Wenn Ihre E-Mail-Vorlage beispielsweise auf zwei Eigenschaften verweist, purchaseUrl und productName, könnten Sie die zugehörigen Werte für diese Eigenschaften mit dem folgenden Anfragetext bereitstellen:

{ "emailId": 4126643121, "message": { "to": "jdoe@hubspot.com" "sendId": "6" }, "customProperties": { "purchaseUrl": "https://example.com/link-to-product", "productName": "vanilla" } }

Sie können dann auf diese Eigenschaften in Ihrer E-Mail-Vorlage verweisen:

<!doctype html> <html> <p> Congrats on purchasing some of the best ice cream around. </p> <a href={{custom.purchaseUrl}}>{{custom.productName}}</a> </html>

Das customProperties-Feld unterstützt nur Arrays, wenn es mitprogrammierbaren E-Mail-Inhalten verwendet wird. In Ihrer E-Mail-Vorlage können Sie auf die in Ihrem customProperties-Feld definierten Elemente mithilfe eines HubL-Ausdrucks verweisen (z. B. mithilfe einer for-Schleife, um jedes Element in einer Liste zu rendern). Zum Beispiel, wenn die customProperties, die Sie in Ihren Anfragetext aufgenommen haben, wie der folgende JSON-Snippet strukturiert war:

{ "emailId": 4126643122, "message": { "to": "jdoe@hubspot.com" "sendId": "7" }, "customProperties": { "exampleArray": [ {"firstKey": "someValue", "secondKey": "anotherValue"}, {"firstKey": "value1", "secondKey": "value2" } ] } }

Sie können dann für jedes Element in exampleArray mit dem folgenden HubL-Code auf die Werte verweisen:

<!doctype html> <html> <p> Thanks for your recent purchase! Here are the details of the items you'll be receiving: </p> <ul> {% for item in custom.exampleArray %} <li>First key: {{ item.firstKey }}, Second key: {{item.secondKey}}</li> {% endfor %} </ul> </html>

Nach dem Senden würde die Transaktions-E-Mail den Inhalt der zugehörigen programmierbaren E-Mail-Vorlage wie folgt wiedergeben:

example-transactional-email-with-customProperties-array

Query the status of an email send

Um den Status des E-Mail-Versands abzurufen, nehmen Sie eine GET-Anfrage an https://api.hubapi.com/marketing/v3/email/send-statuses/{statusId} vor. 

Die Antwort enthält die folgenden Felder:

    • sendResult: eine Aufzählung, die den Sendestatus der E-Mail darstellt. Die möglichen Werte sind unten aufgeführt.
    • requestedAt: der Zeitstempel, an dem der Versand angefordert wurde.
  • startedAt: der Zeitstempel, an dem der Versand verarbeitet wurde.
  • completedAt: der Zeitstempel, an dem der Versand abgeschlossen wurde.
  • statusId: eine ID, die zum Abfragen des Versandstatus verwendet werden kann.
  • status: der Status der Versandanfrage. Umfasst PENDING, PROCESSING, CANCELED und COMPLETE.
  • eventId: bei einem Versand, die ID und der erstellte Zeitstempel des gesendeten Ereignisses.

sendResult

Das sendResult ist eine Aufzählung, die das Ergebnis eines E-Mail-Sendeversuchs darstelllt. Seine möglichen Werte sind:

  • SENT: Die E-Mail wurde erfolgreich gesendet.
  • QUEUED: Die E-Mail wurde in die Warteschlange eingefügt und wird gesendet, wenn die Warteschlange abgearbeitet wird.
  • PORTAL_SUSPENDED: Aufgrund von Verletzungen der Richtlinie zur akzeptablen Nutzung wurde die E-Mail des HubSpot-Kunden ausgesetzt.
  • INVALID_TO_ADDRESS: Die Empfängeradresse ist ungültig.
  • BLOCKED_DOMAIN: Die Domain kann zu diesem Zeitpunkt keine E-Mails von HubSpot empfangen.
  • PREVIOUSLY_BOUNCED: Eine vorangegangene E-Mail konnte dem Empfänger nicht zugestellt werden und die Versandlogik hat keinen Versand zurückgegeben.
  • PREVIOUS_SPAM: Der Empfänger hat bereits eine ähnliche E-Mail als Spam gekennzeichnet.
  • INVALID_FROM_ADDRESS: Die Absenderadresse ist ungültig.
  • MISSING_CONTENT: emailId ist ungültig oder emailId entspricht einer E-Mail, die nicht für Single-Send eingerichtet wurde.
  • MISSING_TEMPLATE_PROPERTIES: Es gibt Eigenschaften, die in der Vorlage festgelegt wurden, die nicht in den customProperties der Anfrage gesendet wurden.
War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.