Verwenden der E-Mail-API für den Zugriff auf E-Mails auf der Interaktionszeitachse

Mit der E-Mail-API können Sie auf E-Mails zugreifen, die Sie an Ihre Kunden gesendet haben, um sicherzustellen, dass Sie über einen zuverlässigen und überprüfbaren Datensatz verfügen. Verwenden Sie diese API, um auf E-Mails auf der Interaktionszeitachse zuzugreifen und sie für die Datensatzhaltung zu exportieren. Auf E-Mails kann bis zu einem Jahr über die API zugegriffen werden.

Übersicht über die E-Mail-API

API-Endpunkt

POST <Organization URL>/api/data/v9.0/msdynmkt_EmailRetrieveExactMessages

Die <Organisations-URL> sollte durch die tatsächliche URL des API-Endpunkts der Organisation ersetzt werden.

Anforderungsheader

Kopfzeile Erforderlich Wert/Beispiel Hinweise
Akzeptieren Ja application/json Die API erfordert JSON-Antworten.
Content-type Ja application/json Anforderungstext muss JSON sein.
Autorisierung Ja Bearer eyJ0eXAiOiJKV1Qi... OAuth 2.0-Bearertoken.

Anforderungsparameter

Parameter Typ Description
Profil-ID GUID Die ID des Zielgruppenmitglieds.
journeyId GUID Die ID der Zielreise.
journeyRunId GUID Die ID der Journeyversion.
messageTemplateId GUID Die ID der zielbezogenen E-Mail.
id String Eine beliebige eindeutige Zeichenfolge. Es wird in der Antwort wieder wiedergegeben, um die Anforderung und das Ergebnis zu korrelieren.
interaktionenJson JSON Zeichenfolgen-JSON-Array, das den Interaktionskontext beschreibt. Jedes Element enthält eine eindeutige ID und ein Eigenschaftenobjekt mit Schlüsseln für die oben beschriebene Reise- und Vorlagenauflösung.

JSON anfordern

Parameter Wert
ProfileId Gezielte ProfileID
MessageEntityName "msdynmkt_email"
Aktivitäten interactionsJson aus der obigen Tabelle

Beispiel

{
    "ProfileId":"0862dc41-0642-f011-877a-6045bd06d212",
    "MessageEntityName":"msdynmkt_email",
    "Interactions":"[{\"id\":\"0862dc41-0642-f011-877a-6045bd06d212_cb883756-f2ba-f011-bbd2-000d3a3212e8_c9921dd4-1e5c-3c3c-d681-0209a0c4d6bc_4dbaa872-62ba-f011-bbd2-000d3a3212e8\",\"properties\":{\"msdynmkt_journeyid\":\"cb883756-f2ba-f011-bbd2-000d3a3212e8\",\"msdynmkt_journeyrunid\":\"c9921dd4-1e5c-3c3c-d681-0209a0c4d6bc\",\"msdynmkt_messagetemplateid\":\"4dbaa872-62ba-f011-bbd2-000d3a3212e8\"}}]"
}

API-Voraussetzungen

  1. Aktivieren Sie die API: Die API greift auf E-Mails zu, die auf der Interaktionszeitachse gespeichert sind. Um die API verfügbar zu machen, müssen Sie die Funktion zum Anzeigen von E-Mails in der Zeitleiste aktivieren.
  2. Authentifizierung: Sie müssen über eine authentifizierte Verbindung verfügen, um auf die API zuzugreifen. Sie müssen ein Zugriffstoken generieren und als Teil Ihrer API-Anforderung mit prvReadWorkflow Berechtigungen verwenden.
  3. Fabric-Integration: Die Anforderungsparameter werden in der EmailSent Tabelle gespeichert. Sie können mithilfe der Fabric-Integration auf diese Tabelle zugreifen, um Einen eigenen benutzerdefinierten Bericht zu erstellen. Basierend auf Ihren Anforderungen können Sie die erforderlichen GUIDs abrufen (z. B. alle E-Mails, die in einem bestimmten Zeitraum gesendet wurden, alle E-Mails, die von einer bestimmten Reise gesendet wurden usw.).

Antwortkörper

Antwortfelder der obersten Ebene

Feld Typ Description
@odata.context String OData-Metadaten-URI für den Antworttyp.
ApiResponseData String Stringified JSON mit den exactMessagesMap und interactionToMessageMap. Analysieren Sie dies, um auf E-Mail-Inhalte zuzugreifen.
Ergebniscode Nummer 200 zeigt erfolg an. Jede Nicht-200-Nummer bedeutet, dass der Vorgang fehlgeschlagen ist.
Fehler Zeichenfolge oder null Wenn ResultCode != 200, enthält dies die Fehlerbeschreibung, andernfalls NULL.

Relevante ApiResponseData Felder

Feld Typ Description
exactMessagesMap Objektkarte Ein Wörterbuch, das anhand der Nachrichten-ID zugeordnet ist. Jeder Wert enthält die gerenderten Nachrichteneigenschaften, einschließlich msdynmkt_emailbody.
exactMessagesMap[<messageId>].msdynmkt_emailbody Zeichenfolge (HTML) Der genaue gerenderte E-Mail-Text, der an das Profil gesendet wurde.
interactionToMessageMap Objektkarte Ordnet jede ID aus der Anfrage der aufgelösten Nachrichten-ID zu. In vielen Fällen ist dies möglicherweise dieselbe Zeichenfolge, aber verlassen Sie sich nicht darauf; behandeln Sie sie als Abbildung.

Beispiel

{
    "@odata.context":"{orgUrl}/api/data/v9.0/$metadata#Microsoft.Dynamics.CRM.msdynmkt_EmailRetrieveExactMessagesResponse",
    "ApiResponseData":"{\"exactMessagesMap\":{\"0862dc41-0642-f011-877a-6045bd06d212_cb883756-f2ba-f011-bbd2-000d3a3212e8_c9921dd4-1e5c-3c3c-d681-0209a0c4d6bc_4dbaa872-62ba-f011-bbd2-000d3a3212e8\":{\"msdynmkt_name\":null,\"msdynmkt_marketingemailid\":null,\"msdynmkt_fromname\":null,\"msdynmkt_fromemail\":null,\"msdynmkt_emailbody\":\"<html>REDACTED</html>\"}},\"interactionToMessageMap\":{\"0862dc41-0642-f011-877a-6045bd06d212_cb883756-f2ba-f011-bbd2-000d3a3212e8_c9921dd4-1e5c-3c3c-d681-0209a0c4d6bc_4dbaa872-62ba-f011-bbd2-000d3a3212e8\":\"0862dc41-0642-f011-877a-6045bd06d212_cb883756-f2ba-f011-bbd2-000d3a3212e8_c9921dd4-1e5c-3c3c-d681-0209a0c4d6bc_4dbaa872-62ba-f011-bbd2-000d3a3212e8\"}}",
"ResultCode":200,
"Error":null
}

Verwendungsbeispiel

# Variables
$tenantId    = "n490b1w9-8975-6t45-b844-8fyuo12cc5we" # your Tenant ID
$appId    = "fjgg175f-9w2w-4156-e9od-w05f8lk9324" # Application (client) ID
$clientSecret = "<secret>"  # Client secret
$resource    = "https://yourorg.crm10.dynamics.com" # You dynamics organization url

# Token endpoint
$tokenUrl = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"

# Request body
$body = @{
    grant_type    = "client_credentials"
    client_id     = $appId
    client_secret = $clientSecret
    scope         = "$resource/.default"
}

# Get token
$response = Invoke-RestMethod -Method Post -Uri $tokenUrl -Body $body
$accessToken = $response.access_token

# API endpoint
$apiUrl = "https://yourorg.crm10.dynamics.com/api/data/v9.0/msdynmkt_EmailRetrieveExactMessages"

# Request params
$profileId = "543ab9o9-5433-23e2-t5t5-ba890d1n5n52"
$journeyId = "a3f7c2d1-58b4-4e21-9c3d-7f8a9b0d1234";
$journeyRunId = "e4b9d7ac-7f21-4c8e-bb3a-9d6f2a4c8e12";
$messageTemplateId = " f2a7c9d3-8b04-4f12-9e67-0034a8b7d5e1";

$interactionsJson = @(
    @{
        id = "$($profileId)_$($journeyId)_$($journeyRunId)_$($messageTemplateId)"
        properties = @{
            msdynmkt_sourcesystem      = "0"
            msdynmkt_journeyid         = $journeyId
            msdynmkt_journeyrunid      = $journeyRunId
            msdynmkt_messagetemplateid = $messageTemplateId
        }
    }
) | ConvertTo-Json -Depth 5 -Compress -AsArray

# Build the request JSON
$requestJson = @{
    ProfileId          = $profileId
    MessageEntityName  = "msdynmkt_email"
    Interactions       = $interactionsJson
} | ConvertTo-Json -Depth 5 -Compress

# Call API
$headers = @{
    Authorization = "Bearer $accessToken"
    "Content-Type" = "application/json"
    Accept = "application/json"
}

Write-Host "Requesting email content for profileId '$profileId', journeyId '$journeyId', journeyRunId '$journeyRunId', messageTemplateId '$messageTemplateId'"

try {
    $apiResponse = Invoke-RestMethod -Method Post -Uri $apiUrl -Headers $headers -Body $requestJson

    if ($apiResponse.ResultCode -eq 200) {
        Write-Host $apiResponse
    }  
    else {
        Write-Host "Result Code $apiResponse.ResultCode: $apiResponse.Error"
    }
    
}
catch {
    Write-Host "Exception occurred: $($_.Exception.Message)"

    if ($_.ErrorDetails.Message) {
        Write-Host "Response Body:$($_.ErrorDetails.Message)"
    }
}
  • Last updated on