EmailEngagementTrackingReportReceived missing recipient that was previously present

Question

Our EmailEngagementTrackingReportReceived events continue to arrive as expected and even though JavaScript SDK defines "AcsEmailEngagementTrackingReportReceivedEventData"'s "recipient" field as just a string (not nullable, not undefined), it is somehow still arriving without it when we receive an event. This causes us to not being able to track engagement events at all, because an email that should be there, isn't.

Here's an example of an event just a few days ago:

{
  "id": "d69f7c96-d81b-4221-a59c-b462d4f7f109",
  "topic": "REDACTED",
  "subject": "REDACTED",
  "data": {
    "sender": "REDACTED",
    "recipient": "REDACTED",
    "messageId": "83d271ee-22ec-4faf-99e3-bb4353c26cc9",
    "userActionTimestamp": "2025-05-15T06:19:59.7300143+00:00",
    "engagementContext": "",
    "userAgent": "REDACTED",
    "engagementType": "view"
  },
  "eventType": "Microsoft.Communication.EmailEngagementTrackingReportReceived",
  "eventTime": "2025-05-15T06:19:59.827Z",
  "metadataVersion": "1",
  "dataVersion": "1.0"
}

Note how it contains "recipient". Compare this to new events:

{
  "id": "b0a7e1b8-ffd2-4df5-bffb-fd1d5cc82fa6",
  "topic": "REDACTED",
  "subject": "REDACTED",
  "data": {
    "sender": "REDACTED",
    "messageId": "4e421036-0bf2-474d-b1c1-17250845ba6b",
    "userActionTimestamp": "2025-05-17T15:53:30.14208+00:00",
    "engagementContext": "REDACTED",
    "userAgent": "REDACTED",
    "engagementType": "click"
  },
  "eventType": "Microsoft.Communication.EmailEngagementTrackingReportReceived",
  "eventTime": "2025-05-17T15:53:30.288Z",
  "metadataVersion": "1",
  "dataVersion": "1.0"
}

Where did recipient go?

Answer 1

Hi Santeri Elo,

You're experiencing an issue where the recipient field in the EmailEngagementTrackingReportReceived event is sometimes missing, making it hard to track email engagement per recipient, which is important for your analytics and attribution.

The recipient field is supposed to always be present in the AcsEmailEngagementTrackingReportReceivedEventData model, but you're now getting events (like clicks) where it's missing. This doesn't match the expected behavior from the SDK and likely points to a backend issue or schema mismatch in Azure Communication Services (ACS) Email tracking.

If the recipient field is missing, your system can't link engagement events to specific email addresses, which breaks your tracking.

• Update your event handler to safely handle missing recipient fields and log key details like messageId, engagementType, and timestamp for tracking.

Here’s a JavaScript/TypeScript example:

if (!event.data.recipient) {
  console.warn(`Missing recipient for engagementType: ${event.data.engagementType}, messageId: ${event.data.messageId}`);
  // Optionally retry or flag for reprocessing
}

• You can use the messageId in the event payload to identify the recipient assuming you stored the mapping between messageId and recipient when sending emails through Azure Communication Services (ACS).
• Since this is a backend issue with Azure Communication Services, we recommend raising a support ticket to report the inconsistency, confirm if it's expected or a bug, and ask about a fix or schema update.

https://learn.microsoft.com/en-us/azure/event-grid/event-schema-communication-services#events-types

Please accept as "Yes" if the answer provided is useful, so that you can help others in the community looking for remediation for similar issues.

Let me know if you have any further Queries.

Answer 2

Hi Santeri,

This issue you're encountering seems to stem from a discrepancy in the event payloads that are being emitted by Azure Communication Services (ACS), specifically the Microsoft.Communication.EmailEngagementTrackingReportReceived event type.

Root Cause Analysis:

Even though the JavaScript SDK defines the recipient field in the AcsEmailEngagementTrackingReportReceivedEventData as a non-nullable string, in practice, there are cases where this field is omitted altogether from the payload.

There are a few potential causes for this:

1. SDK/Service-Level Bug or Inconsistency: It's likely that this is a backend-side issue with how Azure emits tracking events. If the recipient is not correctly resolved or logged during certain user actions (like link clicks or certain email client interactions), ACS might still trigger the event but fail to populate all expected fields.

Changes in Event Schema (Silent Update): Occasionally, Microsoft services roll out updates to event schemas without clear versioning or documentation. It’s possible that under certain engagement types (like click), the recipient is not included anymore — either by design or due to a regression.

Engagement Context Variability: Some email clients or anti-tracking mechanisms might block or strip identifying information from engagement callbacks (especially for click events), resulting in partial event payloads.

Suggested Workarounds:

Add Fallback Handling: Update your event processing pipeline to gracefully handle missing recipient fields, especially for click events. You can log these cases for further investigation without breaking your engagement tracking system.

Use messageId as a Reference: If you're storing messageId along with recipient on send, you might be able to map back the recipient from your own storage by looking up the messageId on received engagement events.

Raise a GitHub Issue or Azure Support Ticket: If this is a blocking issue and not expected behavior, I recommend submitting a GitHub issue here or opening a support case through Azure Portal to bring this to the attention of the product team.

Recommendation:

Until the ACS team clarifies or resolves this issue, do not assume the presence of all fields, even if the SDK types suggest they should always be there. Use defensive programming around the recipient field and consider caching original email-sending metadata for reference.

Hope this helps you move forward!