Set up Event Publishing - Direct Mail - Alibaba Cloud Documentation Center

This topic describes how to integrate Direct Mail with Alibaba Cloud EventBridge to distribute notifications for email delivery results.

After you configure EventBridge, the delivery results of emails sent through Direct Mail are sent to specified event targets, such as MNS and HTTP, based on the Event Publishing rules that you set in EventBridge. This lets you asynchronously obtain the delivery results.

The following sections describe how to set up Event Publishing.

Activate EventBridge and grant access permissions

1. On the Alibaba Cloud home page, search for EventBridge and activate the service. The service is free of charge.

Create an event rule

In the EventBridge console, choose Cloud Service Dedicated Event Bus > Create Rule to create an Event Publishing rule for Direct Mail. Configure the basic information by entering a rule name and a description.

Configure the event pattern. Set Event Source Type to Alibaba Cloud Service Event Source. Select acs.dm as the event source. The supported event types are Send Failed, Send Succeeded, Link Clicked, and Email Opened. You can add event types as needed. Event types that are not added will be filtered out.

Configure the event target. Select a service type. This topic uses MNS as an example. Specify the destination queue. For more information about how to activate MNS and create a queue, see the Activate MNS and create a queue to receive messages section in this topic. By default, the message body is set to Complete Event, and Base64 encoding is disabled. You can configure retry and dead-letter queue options as needed. After the configuration is complete, click Create Rule.

After the rule is created, you can view it on the EventBridge overview page.

Event types and modification methods

Supported event types

Event type	Value of the type parameter
An email fails to be sent	dm:Deliver:Fail
An email is sent	dm:Deliver:Succeed
An email is blocked via FBL	dm:Feedback:FblReport
An email is clicked	dm:Trace:Click
An email is opened	dm:Trace:Open

Modify statistics for different event types

In the navigation pane on the left, click Event Rules. Find the rule and click Edit in the Actions column. In the Configure Event Pattern step, you can modify the event types.

Prerequisites for collecting statistics on open and click events

To distribute notifications for email open and click events, you must first enable the data tracking feature. For more information, see How do I enable data tracking?.

Enable Event Publishing in the Direct Mail console

In the Direct Mail console, turn on the Event Publishing switch.

b3070724625e6b3377fe779d96bf76ec

Receive Event Publishing messages and verify the validation chain

This section uses the event target MNS that is set in the preceding procedure as an example to describe how to verify the Event Publishing validation chain.

Activate MNS and create a queue to receive messages

Log on to the Message Service (MNS) console. If you have not activated MNS, follow the on-screen instructions to activate the service.
In the navigation pane on the left, click Queues to go to the Queues page.
Click Create Queue. The Create Queue dialog box appears.
Enter a queue name. You can specify a custom queue name. In this example, a queue named delivery-result-queue is created. Keep the default values for other parameters and click OK.

Trigger and view Event Publishing

After you send an email using Direct Mail, you can view the event trace records in the EventBridge console.

View the results of the event target

Open the MNS console. In the queue list, find the queue that is configured as the event target in EventBridge. In this example, the queue is delivery-result-queue. Click Send/Receive Messages. You are redirected to the Send and Receive Messages page.

Click Receive Message at the bottom of the page. You can view the event message that was just sent. Click Details to view the complete event message content. You can see that the event ID is the same as the record in EventBridge, which indicates that the event was successfully delivered to MNS.

Example of setting up Event Publishing for a specific sender address

The Event Publishing configured in the preceding example takes effect for all email domains and sender addresses in Direct Mail. You can modify the JSON string of the event rule to distribute events based on filter conditions, such as the sender address, to meet your business requirements.

The following example shows how to configure Event Publishing for a specific sender address, 'batch@sg.example.top'. After you configure the rule, only the record messages of emails sent from 'batch@sg.example.top'.top are delivered to the event target by EventBridge.

1. When you create an event rule, specify the content of the event pattern in the Pattern Content field to filter events based on specific fields.

In this example, the pattern content is as follows:

{
    "source": [
        "acs.dm"
    ],
    "type": [
        "dm:Deliver:Fail",
        "dm:Deliver:Succeed",
        "dm:Trace:Click",
        "dm:Trace:Open",
        "dm:Feedback:FblReport"
    ],
    "data": {
        "from": [
            "batch@sg.example.top"
        ]
    }
}

The following code shows a complete event message body. You can write the pattern content for the event rule based on the content and structure of the event body. For more information, see Event pattern.

All field names in the pattern content must exist in the event body. Otherwise, the event message is filtered out.
The field names in the event pattern must have the same nested structure as the field names in the event.
The event pattern performs an exact match character by character. The matching is case-sensitive. No string standardization is performed during the matching process.
The values to be matched must follow JSON rules: strings enclosed in quotation marks, numbers, and the keywords true, false, and null without quotation marks.
The event pattern supports OR semantics. The keys in the event pattern matching support AND semantics. The values of the keys support OR semantics for arrays.

The following code shows the default message body of an event.

dm:Deliver:Succeed

{
    "datacontenttype": "application/json;charset=utf-8",
    "aliyunaccountid": "1491110661959791",
    "data": {
        "rcpt": "example@example.com",
        "deliver_time": "2024-05-22T08:27:42Z",
        "err_code": "250",
        "failed_type": "SendOk",
        "env_id": "600000083914199845",
        "send_time": "2024-05-22T08:27:41Z",
        "err_msg": "250 Send Mail OK",
        "header": {},
        "from": "example2@example.com",
        "event": "dm:Deliver:Succeed",
        "region": "cn-hangzhou",
        "msg_id": "d93a742c-adec-487d-8c39-98069c583760@example.net",
        "account": "example2@example.com",
        "status": 0
    },
    "subject": "acs:dm:cn-hangzhou:1491110661959791:*",
    "aliyunoriginalaccountid": "1491110661959791",
    "source": "acs.dm",
    "type": "dm:Deliver:Succeed",
    "aliyunpublishtime": "2024-05-22T08:27:42.539Z",
    "specversion": "1.0",
    "aliyuneventbusname": "default",
    "id": "1223c134-b66d-4d53-b05e-780c0261ce22",
    "time": "2024-05-22T08:27:42.462Z",
    "aliyunregionid": "cn-hangzhou"
}

dm:Deliver:Fail

{
    "datacontenttype": "application/json;charset=utf-8",
    "aliyunaccountid": "1406423658557179",
    "data": {
        "rcpt": "dm-cccxcvzsupp***@alibaba-inc.com",
        "channel_name": "bg:alibabak",
        "deliver_time": "2025-05-06T08:25:35",
        "err_code": "554",
        "outbound_ip": "8.219.XX.XX",
        "failed_type": "SmtpNxBox",
        "env_id": "576461125340473909",
        "send_time": "2025-05-06T08:25:30",
        "err_msg": "554  RCPT (dm-cccxcvzsupport@alibaba-inc.com) dosn't exist",
        "header": {},
        "from": "dm@email.sdyyr.top",
        "event": "dm:Deliver:Fail",
        "region": "ap-southeast-1",
        "msg_id": "d00cacd9-4c40-4b0a-b049-ea35b5d06573@email.sdyyr.top",
        "account": "dm@email.sdyyr.top",
        "status": 2
    },
    "subject": "acs:dm:ap-southeast-1:1406423658557179:*",
    "aliyunoriginalaccountid": "1406423658557179",
    "source": "acs.dm",
    "type": "dm:Deliver:Fail",
    "aliyunpublishtime": "2025-05-06T08:25:35.634Z",
    "specversion": "1.0",
    "aliyuneventbusname": "default",
    "id": "b2063370-2e17-4be8-b19e-d912690f5aa1",
    "time": "2025-05-06T08:25:35.622Z",
    "aliyunregionid": "ap-southeast-1"
}

dm:Trace:Click

{
    "datacontenttype": "application/json;charset=utf-8",
    "aliyunaccountid": "1406423658557179",
    "data": {
        "rcpt": "dm-supp***@alibaba-inc.com",
        "env_id": "576461125225614607",
        "operateTime": "2025-05-06T08:33:41",
        "from": "dm@email.sdyyr.top",
        "client_ip": "42.120.XX.XXX",
        "userKp": "1406423658557179",
        "event": "dm:Trace:Click",
        "region": "ap-southeast-1",
        "msg_id": "8c34b82a-9a94-4e06-9579-963e846a688c@email.sdyyr.top",
        "url": "https://example.com"
    },
    "subject": "acs:dm:ap-southeast-1:1406423658557179:*",
    "aliyunoriginalaccountid": "1406423658557179",
    "source": "acs.dm",
    "type": "dm:Trace:Click",
    "aliyunpublishtime": "2025-05-06T08:33:41.472Z",
    "specversion": "1.0",
    "aliyuneventbusname": "default",
    "id": "0bf882fe-c9f8-4a29-bf26-7f0df7540c1c",
    "time": "2025-05-06T08:33:41.469Z",
    "aliyunregionid": "ap-southeast-1"
}

dm:Trace:Open

{
    "datacontenttype": "application/json;charset=utf-8",
    "aliyunaccountid": "1406423658557179",
    "data": {
        "rcpt": "dm-supp***@alibaba-inc.com",
        "env_id": "576461125225614607",
        "operateTime": "2025-05-06T08:33:36",
        "from": "dm@email.sdyyr.top",
        "client_ip": "42.120.XX.XXX",
        "userKp": "1406423658557179",
        "event": "dm:Trace:Open",
        "region": "ap-southeast-1",
        "msg_id": "8c34b82a-9a94-4e06-9579-963e846a688c@email.sdyyr.top"
    },
    "subject": "acs:dm:ap-southeast-1:1406423658557179:*",
    "aliyunoriginalaccountid": "1406423658557179",
    "source": "acs.dm",
    "type": "dm:Trace:Open",
    "aliyunpublishtime": "2025-05-06T08:33:36.336Z",
    "specversion": "1.0",
    "aliyuneventbusname": "default",
    "id": "a29d082d-3a21-4fa1-91e0-4a4ba183fd73",
    "time": "2025-05-06T08:33:36.335Z",
    "aliyunregionid": "ap-southeast-1"
}

dm:Feedback:FblReport

{
    "id": "45ef4dewdwe1-7c35-447a-bd93-fab****",
    "source": "acs.dm",
    "specversion": "1.0",
    "subject": "acs.dm:cn-hangzhou:123456789098****:215672",
    "time": "2020-11-19T21:04:41+08:00",
    "type": "dm:Feedback:FblReport",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2020-11-19T21:04:42Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "send_time": "1726821644",
        "send_email": "from@example.com",
        "block_email": "to@example.com",
        "subject": "Hello Mr.xxx",
        "message_id": "<msgid***@example.com>",
        "block_time": "1726821667",
        "fbl_isp": "outlook**",
        "fingerprint": "SMTPD_abc****"
    }
}

For more information about the fields, see Direct Mail events.

Note

The time fields in the event details are in UTC format.

2. To verify the sender address, send an email from batch@sg.example.top.

3. You can find this message in the MNS queue. In this example, MNS is used as the event target to receive event messages, which is the same as in the procedure for setting up Event Publishing. You can set the event target as needed.

4. After you send an email from another sender address, you can find the details of the event in the Event Trace of EventBridge. However, you will not receive this event message in MNS. This indicates that callback notifications for the specified sender address are implemented.