Asynchronous notifications deliver email sending results to MNS endpoints. This feature is available only to existing users. New users or those modifying MNS configurations should use Set up event dispatch instead.
When you send an email through Direct Mail, the delivery result is sent to an MNS receiving endpoint (HTTP or message queue) based on your event notification rule. You can then asynchronously retrieve the delivery result from that endpoint.
-
You must first create an event notification rule in the MNS console, then create an asynchronous notification in the Direct Mail console. This requires MNS activation, which may incur fees.
-
MNS does not support RAM users. Use your Alibaba Cloud account to set up asynchronous notifications.
Create an event notification rule
Before you create an event notification rule, create a message queue as the receiving endpoint.
Create a queue to receive messages
-
Log on to the MNS console.
-
In the navigation pane on the left, click Queues.
-
Click Create Queue. The Create Queue dialog box appears.
-
Enter a queue name, retain the default values for the other parameters, and then click OK.
Create an event notification rule
1. In the MNS console, click Event Notifications in the navigation pane on the left.
2. Click Create Rule. The Create Rule dialog box appears.
3. Verify the region and product name. Enter a rule name. Select the event types. Add a receiving endpoint. Then, click OK. The receiving endpoint can be an HTTP endpoint or a queue. You can select the queue that you created as the receiving endpoint.
This feature is available only to existing users. New users or those modifying MNS configurations should use Set up event dispatch instead.
Note: A new rule takes about 10 minutes to take effect.
The following sections describe supported event types.
Create an asynchronous notification
Direct Mail supports account-level and sender address-level notifications. Account-level notifications apply to all sender addresses. Sender address-level notifications apply only to specific addresses. You can configure both types simultaneously. Sender address-level notifications take priority — if a sender address has a specific notification configured, those settings are used; otherwise, account-level settings apply.
Create an account-level asynchronous notification
1. Log on to the Direct Mail console.
2. In the navigation pane on the left, click Asynchronous Notifications.
3. Click Create Account-level Asynchronous Notification. A dialog box appears.
4. Select the same region that you selected when you created the event notification rule, and then click OK.
Create a sender address-level asynchronous notification
1. Log on to the Direct Mail console.
2. In the navigation pane on the left, click Asynchronous Notifications.
3. Click the Sender Address-level Asynchronous Notification tab.
4. Click Create Sender Address-level Asynchronous Notification.
5. In the dialog box that appears, select a sender address and a region, and then click OK.
Receive queue messages in the MNS console and verify the connection
After you send an email using the Direct Mail server:
1. Log on to the MNS console.
2. In the navigation pane on the left, click Queues.
3. Select the correct region and find the queue that you created. View the number of active messages in the queue.
4. In the Actions column of the queue, click Send/Receive Messages to view the message details.
Retrieve messages programmatically
For more information, see Direct Mail.
Event types and how to enable them
The following event types are supported:
-
Delivery succeeded: Deliver:SendSuccessfully
-
Failed delivery: Deliver:SendFailed
-
Email open: Deliver:Open
-
Link click: Deliver:Click
Enable statistics for successful or failed delivery events
No additional configuration is required. Delivery information is collected by default.
Enable statistics for open or click events
To enable these events, see Enable tracking for open and click events.
Message structure for successful and failed deliveries
Example of a successful delivery
X-Notify-Message-ID=3121639760461820&env_id=12769055421&msg_id=37483d95-7a08-41fb-9738-3d3ffa24d415@example.com&account=example@example.com&
from=a***@example.net&rcpt=a1***@example.com&recv_time=2017-03-29 14:22:40&end_time=2017-03-29 14:22:43&status=0&event=deliver®ion=cn-hangzhou&err_code=250&err_msg=250 Send Mail OK&failed_type=SendOk
Example of a failed delivery
X-Notify-Message-ID=3121639760461824&env_id=12625010655&msg_id=ac349efc-0d79-489b-affa-f178dce3e49e@example.com&account=example@example.com&
from=a***@example.net&rcpt=a1***@example.net&recv_time=2017-03-28 19:09:49&end_time=2017-03-28 19:09:51&status=4&event=deliver®ion=cn-hangzhou&err_code=524&err_msg=524 Host not found by dns resolve [@ou070302]&failed_type=SysOutDnsResolveFail
How to parse?
The message consists of key-value pairs separated by ampersands (&), with each key and value separated by an equal sign (=). See the parameter list below.
How to distinguish between success and failure messages?
If err_code is not 250, the delivery failed.
If err_code is 250, the delivery succeeded.
Parameter list
|
Name |
Description |
|
X-Notify-Message-ID |
The custom header X-Notify-Message-ID. |
|
env_id |
The internal system ID, which is returned when the email is sent. |
|
msg_id |
The Message-ID field from the original email. |
|
account |
Sender address. |
|
from |
Sender address. |
|
rcpt |
Recipient address. |
|
recv_time |
The time when the email was received by the queue. |
|
end_time |
The time when the email delivery was completed. |
|
status |
The delivery status. 0: success. 2: invalid address. 3: marked as spam by the recipient. 4: failure. |
|
event |
The type of event message. `deliver` corresponds to a delivery event. |
|
region |
The region where the event occurred. |
|
err_code |
The return code from the recipient's Email Service Provider (ESP) upon delivery completion. |
|
err_msg |
The return message from the recipient's ESP upon delivery completion. |
|
failed_type |
The classification of the delivery result. |
Descriptions of common failed_type values:
|
Value |
Semantics and suggestions |
|
SendOk |
Delivery successful. |
|
SysOutDnsResolveFail |
DNS resolution for the recipient domain failed. This is usually an invalid domain. Remove this domain from your recipient list. |
|
SmtpMfFreq |
The sender account is throttled. Reduce your sending frequency. |
|
SmtpContSpam |
The content was identified as spam by the recipient. Improve your email content, or stop sending this template to the corresponding recipient domain. |
|
SmtpAuthFail |
SPF, DKIM, or DMARC verification failed. Configure the correct SPF record, check if a DMARC record is configured, and test if DKIM is correct. |
|
SmtpNxBox |
The recipient's system identified the address as invalid. The address is added to your account-level invalid address list. |
|
SysOutInvRcpt |
The address hit the global invalid address list. If you confirm the address is valid, provide feedback to Alibaba Cloud support, or choose to disable the global invalid address list. |
|
SmtpRcptFreq |
Fatigue control was triggered by the recipient's system. Temporarily stop sending emails to this recipient. |
|
SmtpSslTlsErr |
A temporary error occurred. The SSL/TLS connection failed due to a network issue or because the peer was unavailable. Please retry. |
|
SmtpTempErr |
Temporary error. Please retry. |
|
SmtpZPermErr |
Permanent error. Do not retry. Check the return message from the recipient to determine the specific cause of the error. |
|
SysOutSocksConnError |
Too many connection errors. Possible causes: the peer rejected the connection, or the MX address of the recipient domain is incorrect. |
|
SmtpFullBox |
The recipient's mailbox is full. Stop sending emails to this recipient. You can contact the recipient to clear their mailbox or report the issue to their service provider. |
|
SmtpIPFreq |
The recipient's system is throttling the IP address. Reduce your sending speed and retry later. |
|
SysOutSocksError |
Too many connection errors. Possible causes: the peer rejected the connection, or the MX address of the recipient domain is incorrect. |
|
SysOutConnError |
Too many connection errors. Possible causes: the peer rejected the connection, or the MX address of the recipient domain is incorrect. |
|
SysOutConnTooMuch |
Too many connection errors. Possible causes: the peer rejected the connection, or the MX address of the recipient domain is incorrect. |
|
UnkSmtpError |
Unknown error. Check your sender settings and the recipient address based on the error message. After you confirm that everything is correct, send the email again later. |
|
SmtpMfdFreq |
The email domain is throttled. Reduce your sending frequency. |
|
SmtpMiscSpam |
The content was identified as spam by the recipient. Improve your email content. |
|
SmtpMfBad |
The sender was blacklisted by the recipient's system. Stop sending emails to the recipient, or contact the recipient's system administrator to request removal from the blacklist. |
|
SmtpSpfFail |
SPF verification failed. Configure the correct SPF record. |
|
SmtpMfLimit |
The number of emails sent by the sender in a day exceeded the limit of the recipient domain. Retry the next day. |
|
SmtpDmaFail |
For a domain with DMARC configured, the email was blocked because SPF or DKIM verification failed. Configure the correct SPF record and test if DKIM is correct. |
|
SmtpProtErr |
Protocol interaction error with the peer. You can provide feedback to Alibaba Cloud support for troubleshooting. |
|
SysOutRecipientReportedSpam |
The recipient reported your sender address or domain as spam. Stop sending emails to this recipient or recipient domain. |
|
SysOutHoneypot |
The recipient is a honeypot address. Stop sending emails to this address. Otherwise, you may be penalized by anti-spam organizations. |
|
SysOutRecipientUnsubscribed |
The recipient unsubscribed from your sender address or domain. Stop sending emails to this recipient or recipient domain. |
|
SysIncomingInvRcpt |
The address hit the global invalid address list. If you confirm the address is valid, provide feedback to Alibaba Cloud support, or choose to disable the global invalid address list. |
|
SysOutRcptOnAccountLevelBounceList |
The address hit the account-level invalid address list. If you confirm the address is valid, you can delete it from the invalid address list page, or choose to disable the account-level invalid address list. |
|
SmtpDbl |
The address hit the Spamhaus domain blacklist. Pause sending emails and go to check.spamhaus.org to request removal. After your domain is removed from the blacklist, pay attention to your sending quality and do not send emails to unsubscribed users. |
Message structure for email open events
Example
event=Open®ion=cn-hangzhou&env_id=270016664318&msg_id=1688486074.7.1673022065730@example.com&from=a***@example.net&rcpt=a***@example.net&operate_time=2023-01-07 01:43:51
Parameter list
|
Name |
Description |
|
event |
Event name. |
|
region |
The region where the event occurred. |
|
env_id |
The internal system ID, which is returned when the email is sent. |
|
msgid |
The Message-ID field from the original email. |
|
from |
Sender address. |
|
rcpt |
Recipient address. |
|
operate_time |
The time when the event occurred. |
Message structure for email click events
Example
event=Click®ion=cn-hangzhou&env_id=17870283365788973187&msg_id=02785cb2-71b1-4fb5-bdbb-a49dfbe3326f@example.com&from=a***@example.net&
rcpt=a1***@example.net&operate_time=2023-01-12 09:54:09&url=httpsxxx
Parameter list
|
Name |
Description |
|
event |
Event name. |
|
region |
The region where the event occurred. |
|
env_id |
The internal system ID, which is returned when the email is sent. |
|
msgid |
The Message-ID field from the original email. |
|
from |
Sender address. |
|
rcpt |
Recipient address. |
|
operate_time |
The time when the event occurred. |
|
url |
The clicked URL. |