Configure EventBridge event routing for DirectMail-阿里云帮助中心

This topic describes how to use Direct Mail with EventBridge to distribute notifications about email delivery results.

After you configure EventBridge, delivery results for emails sent using Direct Mail are distributed to specified event targets, such as DingTalk, Message Service (MNS), or HTTP endpoints. This distribution follows the event rules that you set in EventBridge. This process lets you retrieve delivery results asynchronously.

The following sections describe how to set up event distribution.

Enable the event distribution feature in the Direct Mail console

In the Direct Mail console, turn on the event distribution switch.

b3070724625e6b3377fe779d96bf76ec

Activate and authorize EventBridge

1. On the Alibaba Cloud homepage, search for EventBridge and activate the service.

Create an event rule

In the EventBridge console, navigate to the dedicated event bus for Alibaba Cloud services and create an event distribution rule for Direct Mail. Configure the basic information by entering a name and description for the rule.

Configure the event pattern. Set Event Source Type to Alibaba Cloud Service Event Source. Set Event Source to acs.dm. The supported event types are Delivery Failure, Delivery Success, Link Click, and Email Open. Add the event types as needed. Events of types that are not added are filtered out.

Note

You can select the acs.dm event source only if the EventBridge console and the Direct Mail console are in the same region.
Do not select the acs.directmail event source.

Configure the event target. Select a service type, such as DingTalk, MNS, or HTTP. For more information, see Manage event rules.

This example uses MNS as the event target. Specify the destination queue. For information about how to activate MNS and create a queue, see the Activate MNS and create a queue for receiving messages section. For the message body, select Complete Event. Do not use Base64 encoding. Configure the retry policy and dead-letter queue as needed. After you complete the settings, 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
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

All types of events that occur within 30 days after an email is sent are pushed to EventBridge.

Modify statistics for event types

In the navigation pane on the left, click Event Rules and then click Edit Event Pattern. You can then modify the event types.

Prerequisites for tracking open or 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?.

Receive event messages and verify the validation chain

The following example uses the Lightweight Message Queue event target configured in the preceding flow to verify the event distribution link.

Activate MNS and create a queue for receiving messages

Go to the MNS console. If MNS is not activated, follow the instructions to activate it.
In the navigation pane on the left, click Queues.
Click Create Queue. The Create Queue dialog box appears.
Enter a name for the queue. This example uses delivery-result-queue. Keep the default values for other parameters and click OK.

Trigger and view event distribution

Send an email using Direct Mail. Then, view the event trail in the EventBridge console.

View the results at the event target

Go to the Lightweight Message Queue console, select the queue that is configured as the EventBridge target from the queue list (for example, delivery-result-queue), and click the Send and Receive Messages button to open the Send and Receive Messages page.

At the bottom of the page, click Receive Message to view the event message. Click Details to view the complete event message content. If the event ID matches the record in EventBridge, the event was successfully delivered to MNS.

Example: Set up event distribution for a specific sender address

The event distribution configured in the previous example applies to all email domains and sender addresses in your Direct Mail service. You can modify the JSON string of the event rule to distribute events based on filter conditions, such as the sender address.

The following example shows how to distribute Direct Mail events for a specific sender address, test@hangzhou.dmtest.top. After you configure the rule, only event messages for emails sent from test@hangzhou.dmtest.top are delivered to the event target.

1. When you create the event rule, specify the details of the event pattern in the Pattern Content section to filter events by specific field content.

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": [
            "test@hangzhou.dmtest.top"
        ]
    }
}

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

All field names in the pattern content must exist in the event body. Otherwise, the event message is filtered.
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, character-by-character match. The match is case-sensitive. No string normalization is performed during the matching process.
The values to match must follow JSON rules: strings in quotation marks, numbers, and the unquoted keywords true, false, and null.
Event patterns support OR semantics. Within a pattern, individual Keys are evaluated using AND semantics, while the Value of a Key is evaluated using array OR semantics.

The following is the default message body for an event.

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 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: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****"
    }
}

The following table describes the 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 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: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"
    }
}

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. 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 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: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"
    }
}

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. 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 result for a graylist address validation is available, 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: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"
    }
}

The following table describes the parameters in the data field.

Parameter	Type	Example	Description
request_id	String	45ef4dewdwe1-7c35-447a-bd93-fab****	The request ID returned by the OpenAPI (Open Application Programming Interface) 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 of the email address after validation. This provides more details about the status.
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 obtained from syntax parsing. The value is converted to lowercase, and the sub-addressing tag (the part after the plus sign) is removed.
domain_part	String	yyy.com	The domain part of the email address obtained from syntax parsing. The value is converted to lowercase.

References: Direct Mail events

Note

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

2. Send a test email from test@hangzhou.dmtest.top.

3. In the lightweight message queue's queue, you can find the message. (In this example, a lightweight message queue is used as the event target to receive event messages, which is similar to an event distribution flow. You can also set your own event target.)

4. Send an email from a different sender address. You can find the event details in the Event Trail of the EventBridge console. However, the MNS queue does not receive this event message. This confirms that the callback notifications are correctly filtered by the specified sender address.