ACS - Email - Delivery or Bounce Event custom properties

ACS Email doesn’t currently expose a way to attach arbitrary custom metadata or a custom correlation ID that is echoed back in Email delivery/bounce/engagement events.

From the available schemas and telemetry:

• Event Grid events for ACS Email use fixed schemas:
  • Microsoft.Communication.EmailDeliveryReportReceived for delivery/bounce status.
  • Microsoft.Communication.EmailEngagementTrackingReportReceived for opens/clicks.
• These events carry ACS-defined properties such as Status / DeliveryStatus and engagement details (for example, engagementType = View or Click, and engagementContext for clicked links), but no user-defined property bag is documented.
• Operational logs and metrics expose ACS-side identifiers and statuses:
  • ACSEmailStatusUpdateOperational includes DeliveryStatus values like Delivered, Bounced, Suppressed, etc., and can be queried to list failed deliveries by RecipientId or by MessageId.
  • Email metrics and insights (bounce rate, blocked rate, user engagement) are based on ACS identifiers and dimensions such as EngagementType.

Given the context, the following can be stated:

1. Mechanism to attach custom metadata
   • No supported mechanism is documented to attach arbitrary custom metadata or custom correlation IDs to ACS Email messages that are then surfaced in Event Grid email events.
2. Roadmap / planned enhancements
   • No roadmap or planned enhancement for custom correlation IDs or user-defined properties is documented in the provided material.
3. Recommended approach for bounce handling and mapping back to source transactions Within the current capabilities, the supported pattern is to use ACS-generated identifiers and logs as the correlation surface:
   • Capture and persist ACS message identifiers at send time:
     • When calling the Email Send API (SendMail operation), persist the returned messageId (and any other ACS identifiers available in the send response) alongside the external platform’s transaction ID.
   • Use ACS operational logs for delivery/bounce status:
     • Query ACSEmailStatusUpdateOperational by MessageId or RecipientId to retrieve delivery outcomes:
       • Example queries from the documentation:
         • Failed deliveries by recipient:

                      ACSEmailStatusUpdateOperational
                      | where isnotempty(RecipientId)
                      | where DeliveryStatus != "Delivered"
                      | limit 100
           

         • Failed deliveries by message ID:

                      ACSEmailStatusUpdateOperational
                      | where isempty(RecipientId)
                      | where DeliveryStatus != "OutForDelivery"
                      | limit 100
           

         • Bounced and suppressed recipients:

                      ACSEmailStatusUpdateOperational
                      | where DeliveryStatus == "Bounced" or DeliveryStatus == "Suppressed"
                      | limit 100
           

     • Join these results with the stored mapping of messageId → external transaction ID in the third‑party platform.
   • Use documented bounce codes and statuses for logic:
     • Delivery/bounce events and logs carry standardized SMTP/DSN codes and ACS delivery statuses such as Delivered, Bounced, Suppressed, Failed, FilteredSpam, Quarantined, etc.
     • The “Email bounces: Delivery statuses and types” tables define error codes (for example, 5.1.1 Bad Destination Mailbox Address, 5.7.23 SPF Validation Failed, 521 Server Doesn't Accept Mail, etc.) and their meanings. These can be used to drive automated suppression, retries, or remediation workflows in the external platform.
   • Use Email Insights and metrics for monitoring:
     • Bounce rate and blocked rate are exposed via Email Insights workbooks and metrics. These can be used for operational monitoring and alerting, even though they are aggregate rather than per-message metadata.
4. Best practices / alternative patterns Based on the documented capabilities, the practical patterns in use today are:
   • Key-based correlation:
     • Treat ACS messageId (and optionally RecipientId) as the primary key for correlation.
     • Store a mapping table in the external platform or a shared data store (for example, Azure Table Storage, Cosmos DB, SQL) that links messageId to the platform’s own correlation ID or transaction record.
   • Log Analytics–driven workflows:
     • Ingest ACSEmailStatusUpdateOperational into Azure Monitor Logs.
     • Use Kusto queries (as shown above) to identify bounces/suppressions and then push those results into the external platform via scheduled jobs or event-driven automation (for example, Logic Apps, Functions) keyed by messageId.
   • Status- and code-based suppression logic:
     • Use the documented error codes and delivery statuses to maintain suppression lists and retry policies in the external platform, aligning with ACS’s own managed suppression behavior.

Within the provided documentation, these ACS-native identifiers and logs are the supported way to achieve reliable bounce handling and correlation when integrating with external communication platforms.

References:

• Azure Communication Services - Email events
• Understand sender reputation in Azure Communication Services email
• Email metrics overview
• Email insights
• Queries for the ACSEmailStatusUpdateOperational table