Configure EventBridge event routing for DirectMail - Direct Mail

Integrate DirectMail with EventBridge to route email delivery notifications to targets such as DingTalk, Message Queue for Apache RocketMQ, and HTTP endpoints.

After you configure the event bus, delivery results for emails sent through DirectMail are routed to specified event targets such as DingTalk, Message Queue for Apache RocketMQ, and HTTP based on your routing rules. This enables asynchronous delivery result retrieval.

Complete the following steps to set up event routing.

Enable event distribution

Turn on the event notification switch in the DirectMail console.

b3070724625e6b3377fe779d96bf76ec

Activate and authorize EventBridge

1. Search for EventBridge on the Alibaba Cloud homepage and activate the service for free.

Create an event rule

In the EventBridge console, navigate to event bus for cloud services > Create Rule. Enter a rule name and description for DirectMail.

Configure the event pattern. Select Alibaba Cloud official event source as the event source type and acs.dm as the event source. Supported event types: Send Failure, Send Success, Link Click, and Email Open. Add event types as needed; unsupported types are filtered out.

To configure the event target, select a service type such as DingTalk, Message Service (MNS), or HTTP. For details, see Manage event rules.

This example uses Message Queue for MQTT as the event target. Specify the destination queue. (To activate Message Queue for MQTT and create a queue, follow the "Activate Message Queue for MQTT and create a receiving queue" section below.) The default message body is the complete event without Base64 encoding. Configure retry and dead-letter options as needed, then click Create Rule.

After creating the rule, view it in the EventBridge console.

Event types and modifications

Supported event types

Event type	Value of the type parameter
Mail delivery failed	dm:Deliver:Fail
Mail delivery succeeded	dm:Deliver:Succeed
Mail FBL report data	dm:Feedback:FblReport
Mail resubscription data	dm:Feedback:Subscribe
Mail unsubscription data	dm:Feedback:UnSubscribe
Click event	dm:Trace:Click
Open event	dm:Trace:Open
Asynchronous result of graylist address validation	dm:Validator:GrayListResult

Note

EventBridge receives events for 30 days after an email is sent.

Configuring statistics for event types

Click Event Rules > Edit Event Pattern > Event Type to modify the event type.

Prerequisites for open and click tracking

To receive notifications for email open and click events, enable data tracking first. Enable data tracking.

Receive event messages and verify links

This example uses the lightweight message queue configured above to verify the event delivery path.

Set up a lightweight message queue

Go to the Message Queue for MQTT console. If Message Queue for MQTT is not activated, follow the prompts to activate it.
In the left navigation pane, click Queues.
Click Create Queue.
Enter a queue name, such as delivery-result-queue. Keep the default settings and click OK.

Trigger event distribution

After sending an email through DirectMail, view the event trace in the EventBridge console.

Event target results

In the lightweight message queue console, select the queue configured as the EventBridge target (delivery-result-queue) and click Send and Receive Messages.

Click Receive Messages to view the event message, then click Details to see the full content. Delivery to Message Service is confirmed if the event ID matches the EventBridge record.

Example: Configure sender address event forwarding

The event distribution configured above applies to all sending domains and addresses in DirectMail. You can modify the event rule JSON to filter events by specific conditions, such as a sender address.

The following example configures a rule that routes DirectMail events for the sender address test@hangzhou.dmtest.top to an event target.

1. When you create an event rule, specify an event pattern to filter events by their fields.

This example uses the following pattern:

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

The following is a complete event message body. Write an event pattern based on its content and structure.

All field names in the event pattern must exist in the event body.
The nested structure of field names in the event pattern must match that of the event.
Matching is exact, character-by-character, and case-sensitive. Strings are not normalized.
Values in the pattern must follow JSON rules: strings enclosed in quotation marks, numbers, and the unquoted keywords true, false, and null.
Event patterns support both AND and OR logic. Different keys within a pattern use AND logic. An array of values for a key uses OR logic.

Default event message body:

Mail delivery failed

When an email fails to be delivered, EventBridge receives an event similar to the following example.

{
  "data": {
    "header": {
      "X-Notify-Message-ID": "test******@******"
    },
    "env_id": "60000******",
    "account": "batch******@top",
    "from": "batch******@top",
    "rcpt": "xxx******@aliyun.com",
    "msg_id": "1df******@******",
    "channel_name": "bg:vip_*",
    "outbound_ip": "8.*.*.7",
    "send_time": "2024-04-29T11:07:04",
    "deliver_time": "2024-04-29T11:07:12",
    "status": "2",
    "event": "dm:Deliver:Fail",
    "region": "cn-hangzhou",
    "err_code": "554",
    "err_msg": "554  RCPT xxx******@aliyun.com dosn't exist",
    "failed_type": "SmtpNxBox",
    "esp": "*mail.com",
    "ip_pool_id": "10306c37-****-****-a82f-1dafb56a9dd2",
    "is_dedicated_ip": true,
    "tag": "xxxxx"
  },
  "id": "8734hhidu983hi457",
  "source": "acs:dm",
  "specversion": "1.0",
  "subject": "acs:dm:cn-hangzhou:{AccountId}:*",
  "time": "2024-04-29T11:07:12+08:00",
  "type": "dm:Deliver:Fail",
  "aliyunaccountid": "123456789098****",
  "aliyunpublishtime": "2024-04-29T11:07:13.179PRC",
  "aliyuneventbusname": "default",
  "aliyunregionid": "cn-hangzhou",
  "aliyunpublishaddr": "172.25.XX.XX"
}

The following table describes the parameters in the data field.

Parameter	Type	Example	Description
header	Object		The headers related to the email.
X-Notify-Message-ID	String	test****@example.com	The custom header X-Notify-Message-ID.
env_id	String	60000****	The email ID returned by the system when the email is sent.
account	String	batch****@top	The email address of the sender.
from	String	batch****@top	The email address of the sender.
rcpt	String	a****@aliyun.com	The email address of the recipient.
msg_id	String	1df****@example.com	The Message-ID field of the email.
channel_name	String	bg:vip_*	The name of the channel to which the outbound IP address for this delivery belongs.
outbound_ip	String	8...7	The outbound IP address for this delivery.
send_time	String	2024-04-29T11:07:04	The time when the email was accepted.
deliver_time	String	2024-04-29T11:07:12	The time when the email delivery was completed.
status	String	2	The delivery status. 0: Succeeded. 2: Invalid address. 3: The recipient marked the email as spam. 4: Other failures.
event	String	dm:Deliver:Fail	The type of the event message. This is the same as the type parameter.
region	String	cn-hangzhou	The region where the event occurred.
err_code	String	554	The code returned by the recipient's email service provider (ESP) upon delivery completion.
err_msg	String	554 RCPT a****@aliyun.com dosn't exist	The message returned by the recipient's ESP upon delivery completion.
failed_type	String	SmtpNxBox	The categorization of the delivery result.
esp	String	*mail.com	The categorization of the recipient's email provider.
ip_pool_id	String	10306c37-**-**-a82f-1dafb56a9dd2	The ID of the IP pool used to send the email.
is_dedicated_ip	Boolean	true	Indicates whether a dedicated IP address was used.
tag	String	xxxxx	The tag used to send the email.

Mail delivery succeeded

When an email is successfully delivered, EventBridge receives an event similar to the following example.

{
  "data": {
    "header": {
      "X-Notify-Message-ID": "test******@******"
    },
    "env_id": "60000******",
    "account": "batch******@top",
    "from": "batch******@top",
    "rcpt": "xxx******@aliyun.com",
    "msg_id": "1df******@******",
    "channel_name": "bg:vip_*",
    "outbound_ip": "8.*.*.7",
    "send_time": "2024-04-29T11:07:04",
    "deliver_time": "2024-04-29T11:07:12",
    "status": "0",
    "event": "dm:Deliver:Succeed",
    "region": "cn-hangzhou",
    "err_code": "250",
    "err_msg": "250 Send Mail OK",
    "failed_type": "SendOk",
    "esp": "*mail.com",
    "ip_pool_id": "10306c37-****-****-a82f-1dafb56a9dd2",
    "is_dedicated_ip": true,
    "tag": "xxxxx"
  },
  "id": "8734hhidu983hi457",
  "source": "acs:dm",
  "specversion": "1.0",
  "subject": "acs:dm:cn-hangzhou:{AccountId}:*",
  "time": "2024-04-29T11:07:12+08:00",
  "type": "dm:Deliver:Succeed",
  "aliyunaccountid": "123456789098****",
  "aliyunpublishtime": "2024-04-29T11:07:13.179PRC",
  "aliyuneventbusname": "default",
  "aliyunregionid": "cn-hangzhou",
  "aliyunpublishaddr": "172.25.XX.XX"
}

For a description of the parameters in the data field, see Parameter descriptions.

Mail FBL report data

When an email is reported through a feedback loop (FBL), EventBridge receives an event like the following:

{
    "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@xxx.com",
        "block_email": "to@yyy.com",
        "subject": "Hello Mr.xxx",
        "message_id": "<msgid***@xxx.com>",
        "block_time": "1726821667",
        "fbl_isp": "outlook**",
        "fingerprint": "SMTPD_abc****"
    }
}

Parameters in the data field:

Parameter	Type	Example	Description
send_time	String	1726821644	The time when the email was sent.
send_email	String	from@xxx.com	The email address of the sender.
block_email	String	to@yyy.com	The email address of the blocked recipient.
subject	String	Hello Mr.xxx	The subject of the email.
message_id	String	<msgid***@xxx.com>	The unique identifier of the email.
block_time	String	1726821667	The time when the email was blocked.
fbl_isp	String	outlook**	The Internet Service Provider (ISP) of the sender.
fingerprint	String	SMTPD_abc****	The fingerprint of the email.

Mail resubscription data

When a recipient resubscribes, EventBridge receives an event like the following:

{
    "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:Subscribe",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2020-11-19T21:04:42Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "operate_time": "2024-04-29T11:25:48",
        "envid": "6000*********",
        "from": "from@xxx.com",
        "rcpt": "to@yyy.com",
        "client_ip": "102.**.**.1"
    }
}

Parameters in the data field:

Parameter	Type	Example	Description
operate_time	String	2024-04-29T11:25:48	The time when the operation occurred. The time is in UTC.
env_id	String	6000*********	The email ID returned by the system when the email was sent.
from	String	from@xxx.com	The sender's address.
rcpt	String	to@yyy.com	The recipient's address.
client_ip	String	102...1	Client IP address for the open event

Mail unsubscription data

When a recipient unsubscribes, EventBridge receives an event like the following:

{
    "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:UnSubscribe",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2020-11-19T21:04:42Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "operate_time": "2024-04-29T11:25:48",
        "envid": "6000*********",
        "from": "from@xxx.com",
        "rcpt": "to@yyy.com",
        "client_ip": "102.**.**.1"
    }
}

Parameters in the data field:

Parameter	Type	Example	Description
operate_time	String	2024-04-29T11:25:48	The time when the operation occurred. The time is in UTC.
env_id	String	6000*********	The email ID returned by the system when the email was sent.
from	String	from@xxx.com	The sender's address.
rcpt	String	to@yyy.com	The recipient's address.
client_ip	String	102...1	The IP address of the source client for the event

Click event

When a recipient clicks a link in an email, EventBridge receives an event similar to the following example.

{
    "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:Trace:Click",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2020-11-19T21:04:42Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "operate_time": "2024-04-29T11:25:48",
        "client_ip": "202.**.**.1",
        "env_id": "60000******",
        "from": "batch******@top",
        "rcpt": "xxx******@aliyun.com",
        "msg_id": "1df******@******",
        "event": "dm:Trace:Click",
        "region": "cn-hangzhou",
        "url": "https://www.aliyun.com",
        "outbound_ip": "102.**.**.1",
        "esp": "*mail.com",
        "ip_pool_id": "10306c37-****-****-a82f-1dafb56a9dd2",
        "is_dedicated_ip": true,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X ****) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1",
        "tag": "xxxxx"
    }
}

The following table describes the parameters in the data field.

Parameter	Type	Example	Description
operate_time	String	2024-04-29T11:25:48	The time when the operation occurred.
client_ip	String	202...1	The IP address of the client that clicked the link.
env_id	String	60000******	The email ID returned by the system when the email was sent.
from	String	batch****@top	The sender's address.
rcpt	String	xxx******@aliyun.com	The recipient's address.
msg_id	String	1df****@****	The Message-ID field in the email.
event	String	dm:Trace:Click	The event type.
region	String	cn-hangzhou	The region where the event occurred.
url	String	https://www.aliyun.com	The URL that was clicked.
outbound_ip	String	102...1	The outbound IP address used to send the email.
esp	String	*mail.com	The categorization of the recipient's email provider.
ip_pool_id	String	10306c37-**-**-a82f-1dafb56a9dd2	The ID of the IP pool used to send the email.
is_dedicated_ip	Boolean	true	Indicates whether a dedicated IP address was used.
user_agent	String	Mozilla/5.0 (Macintosh; Intel Mac OS X ****) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1	The user agent for the click event.
tag	String	xxxxx	The tag used to send the email.

Open event

When an event occurs, EventBridge receives the following sample event.

{
    "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:Trace:Open",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2020-11-19T21:04:42Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "operate_time": "2024-04-29T11:25:48",
        "client_ip": "202.**.**.1",
        "env_id": "60000******",
        "from": "batch******@top",
        "rcpt": "xxx******@aliyun.com",
        "msg_id": "1df******@******",
        "event": "dm:Trace:Open",
        "region": "cn-hangzhou",
        "outbound_ip": "102.**.**.1",
        "esp": "*mail.com",
        "ip_pool_id": "10306c37-****-****-a82f-1dafb56a9dd2",
        "is_dedicated_ip": true,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X ****) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1",
        "tag": "xxxxx"
    }
}

The following table describes the parameters in the data field.

Parameter	Type	Example	Description
operate_time	String	2024-04-29T11:25:48	The time when the operation occurred.
client_ip	String	192.168.XX.XX	The IP address of the client that opened the email.
env_id	String	60000******	The email ID returned by the system when the email was sent.
from	String	batch****@top	The sender's address.
rcpt	String	a****@aliyun.com	The recipient's address.
msg_id	String	1df****@example.com	The Message-ID field in the email.
event	String	dm:Trace:Click	The event type.
region	String	cn-hangzhou	The region where the event occurred.
outbound_ip	String	102...1	The outbound IP address used to send the email.
esp	String	*mail.com	The categorization of the recipient's email provider.
ip_pool_id	String	10306c37-**-**-a82f-1dafb56a9dd2	The ID of the IP pool used to send the email.
is_dedicated_ip	Boolean	true	Indicates whether a dedicated IP address was used.
user_agent	String	Mozilla/5.0 (Macintosh; Intel Mac OS X ****) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1	The user agent for the open event.
tag	String	xxxxx	The tag used to send the email.

Asynchronous result of graylist address validation

When an asynchronous graylist address validation result is available, EventBridge receives an event like the following:

{
    "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:Validator:GrayListResult",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2020-11-19T21:04:42Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "request_id": "45ef4dewdwe1-7c35-447a-bd93-fab****",
        "submission_time": "1763541726",
        "completion_time": "1763541793",
        "email": "xxxxxx@yyy.com",
        "status": "INVALID",
        "sub_status": "MAILBOX_NOT_EXISTS",
        "provider": "XXXX",
        "is_free_mail": false,
        "local_part": "xxxxxx",
        "domain_part": "yyy.com"
    }
}

Parameters in the data field:

Parameter	Type	Example	Description
request_id	String	45ef4dewdwe1-7c35-447a-bd93-fab****	The request ID returned by the API when the request was submitted.
submission_time	String	1763541726	The time when the validation request was submitted. The time is in UTC.
completion_time	String	1763541793	The time when the validation was completed. The time is in UTC.
email	String	xxxxxx@yyy.com	The email address that was validated.
status	String	INVALID	The status of the email address after validation.
sub_status	String	MAILBOX_NOT_EXISTS	The sub-status providing additional details about the validation result.
provider	String	XXXX	The categorization of the email provider for the address.
is_free_mail	Boolean	false	Indicates whether the address is from a free email provider.
local_part	String	xxxxxx	The local part of the email address, converted to lowercase with the sub-addressing tag removed.
domain_part	String	yyy.com	The domain part of the email address, converted to lowercase.

Email push event

Note

All time fields in the event details are in UTC.

2. Send an email from test@hangzhou.dmtest.top to verify the sender.

3. Check the Message Service (MNS) queue for the message. (This example uses Message Service (MNS) as the event target. You can configure a different target.)

4. Send an email from a different sender address, then check EventBridge > event trace. The event appears in the trace but is not delivered to Message Queue for Apache RocketMQ, confirming that notifications are triggered only by the specified sender address.