1、郵件推送API參考手冊(cè)郵件推送/API參考手冊(cè)郵件推送/API參考手冊(cè) PAGE 15 PAGE 15API參考手冊(cè)簡(jiǎn)介歡迎使用阿里云郵件推送服務(wù) DirectMail。用戶可以使用本文檔介紹的 API 對(duì) DirectMail 服務(wù)進(jìn)行相關(guān)操作。請(qǐng)確保在使用這些接口前，已充分了解了DirectMail產(chǎn)品說(shuō)明、使用協(xié)議和收費(fèi)方式。術(shù)語(yǔ)表術(shù)語(yǔ)中文說(shuō)明AccountName郵件地址必須先通過(guò)管理控制臺(tái)預(yù)先創(chuàng)建DirectMailTemplate郵件模板批量發(fā)信時(shí)候預(yù)先創(chuàng)建一個(gè)郵件模板Receiver收件人列表批量發(fā)信時(shí)候預(yù)先創(chuàng)建一個(gè)收信人列表業(yè)務(wù)限制資源規(guī)格限制說(shuō)明在 DirectMail 中，

2、對(duì)每個(gè)用戶可擁有的郵件地址、郵件模板、收件人列表等資源的數(shù)量均有限制。在郵件地址、郵件模板、收件人列表的數(shù)目、每個(gè)賬號(hào)的發(fā)信數(shù)量等規(guī)格方面也有限制。在使用 DirectMail Open API 時(shí)，請(qǐng)參考官網(wǎng)上最新的業(yè)務(wù)限制規(guī)則和資源規(guī)格限制。查詢鏈接在接口說(shuō)明部分，凡出現(xiàn)對(duì)參數(shù)可選值、可用規(guī)格方面與官網(wǎng)上給出的資源規(guī)格限制發(fā)生矛盾時(shí)，均以官網(wǎng)上 給出的值為準(zhǔn)。API概覽API描述發(fā)信郵件相關(guān)接口API描述SingleSendMail單一發(fā)信接口，支持發(fā)送觸發(fā)和批量郵件BatchSendMail批量發(fā)信接口，支持通過(guò)調(diào)用模板的方式發(fā)送批量郵件更新歷史API版本：2015-11-23最近更新時(shí)

3、間：2016-03-18發(fā)布時(shí)間更新說(shuō)明2015-11-23公測(cè)上線提供發(fā)送郵件等操作接口2016-03-18小發(fā)布單一發(fā)信接口添加可選發(fā)信人昵稱參數(shù)調(diào)用方式調(diào)用方式對(duì) DirectMail API接口調(diào)用是通過(guò)向DirectMail API的服務(wù)端地址發(fā)送HTTP的GET或POST請(qǐng)求，并按照接口說(shuō)明在請(qǐng)求中加入相應(yīng)請(qǐng)求參數(shù)來(lái)完成的；根據(jù)請(qǐng)求的處理情況，系統(tǒng)會(huì)返回處理結(jié)果。請(qǐng)求結(jié)構(gòu)公共參數(shù)返回結(jié)果簽名機(jī)制請(qǐng)求結(jié)構(gòu)服務(wù)地址DirectMail API的服務(wù)接入地址為：通信協(xié)議支持通過(guò)HTTP或HTTPS通道進(jìn)行請(qǐng)求通信。為了獲得更高的安全性，推薦您使用HTTPS通道發(fā)送請(qǐng)求。請(qǐng)求方法支持HTT

4、P GET方法發(fā)送請(qǐng)求，這種方式下請(qǐng)求參數(shù)需要包含在請(qǐng)求的URL中。 支持HTTP POST方法發(fā)送請(qǐng)求，這種方式下請(qǐng)求參數(shù)需要包含在請(qǐng)求的BODY中。請(qǐng)求參數(shù)每個(gè)請(qǐng)求都需要指定要執(zhí)行的操作，即Action參數(shù)（例如SingleSendMail），以及每個(gè)操作都需要包含的公共 請(qǐng)求參數(shù)和指定操作所特有的請(qǐng)求參數(shù)。字符編碼請(qǐng)求及返回結(jié)果都使用UTF-8字符集進(jìn)行編碼。公共參數(shù)公共請(qǐng)求參數(shù)公共請(qǐng)求參數(shù)是指每個(gè)接口都需要使用到的請(qǐng)求參數(shù)。名稱類型是否必須描述FormatString否返回值的類型，支持JSON與XML。默認(rèn)為XMLVersionString是API版本號(hào)，為日期形式：YYYY-MM-

5、DD，本版本對(duì)應(yīng)為2015-11-23AccessKeyIdString是阿里云頒發(fā)給用戶的訪問(wèn)服務(wù)所用的密鑰IDSignatureString是簽名結(jié)果串，關(guān)于簽名的計(jì)算方法，請(qǐng)參見(jiàn)簽名機(jī)制。SignatureMethodString是簽名方式，目前支持HMAC-SHA1TimestampString是請(qǐng)求的時(shí)間戳。日期格式按照ISO8601標(biāo)準(zhǔn)表示，并需要使用UTC時(shí)間。格式為YYYY-MM-DDThh:mm:ssZ 例 如，2015-11- 23T04:00:00Z（為北京時(shí)間2015年11月23日12點(diǎn)0分0秒）SignatureVersionString是簽名算法版本，目前版本是1.

6、0SignatureNonceString是唯一隨機(jī)數(shù)，用于防止網(wǎng)絡(luò)重放攻擊。用戶在不同請(qǐng)求間要使用不同的隨機(jī)數(shù)值/?Format=xml &Version=2015-11-23&Signature=Pc5WB8gokVn0 xfeu%2FZV%2BiNM1dgI%3D &SignatureMethod=HMAC-SHA1 /?Format=xml &Version=2015-11-23&Signature=Pc5WB8gokVn0 xfeu%2FZV%2BiNM1dgI%3D &SignatureMethod=HMAC-SHA1 &SignatureNonce=e1b44502-6d13-4

7、433-9493-69eeb068e955 &SignatureVersion=1.0&AccessKeyId=key-test &Timestamp=2015-11-23T12:00:00Z公共返回參數(shù)用戶發(fā)送的每次接口調(diào)用請(qǐng)求，無(wú)論成功與否，系統(tǒng)都會(huì)返回一個(gè)唯一識(shí)別碼RequestId給用戶。4C467B38-3910-447D-87BC-AC049166F216示 例4C467B38-3910-447D-87BC-AC049166F216RequestId: 4C467B38-3910-447D-87BC-AC049166F216/* 返回結(jié)果數(shù)據(jù) */RequestId: 4C467B

8、38-3910-447D-87BC-AC049166F216/* 返回結(jié)果數(shù)據(jù) */返回結(jié)果調(diào)用API服務(wù)后返回?cái)?shù)據(jù)采用統(tǒng)一格式，返回的HTTP狀態(tài)碼為2xx，代表調(diào)用成功；返回4xx或5xx的HTTP狀態(tài) 碼代表調(diào)用失敗。調(diào)用成功返回的數(shù)據(jù)格式主要有XML和JSON兩種，外部系統(tǒng)可以在請(qǐng)求時(shí)傳入?yún)?shù)來(lái)制定 返回的數(shù)據(jù)格式，默認(rèn)為XML格式。本文檔中的返回示例為了便于用戶查看，做了格式化處理，實(shí)際返回結(jié)果 是沒(méi)有進(jìn)行換行、縮進(jìn)等處理的。成功結(jié)果4C467B38-3910-447D-87BC-AC049166F216JSON示例RequestId: 4C467B38-3910-447D-87BC

9、-AC049166F216/* 返回結(jié)果數(shù)據(jù) */錯(cuò)誤結(jié)果調(diào)用接口出錯(cuò)后，將不會(huì)返回結(jié)果數(shù)據(jù)。調(diào)用方可根據(jù)每個(gè)接口對(duì)應(yīng)的錯(cuò)誤碼以及下述2.3.3的公共錯(cuò)誤碼來(lái)定 位錯(cuò)誤原因。當(dāng)調(diào)用出錯(cuò)時(shí)，HTTP請(qǐng)求返回一個(gè)4xx或5xx的HTTP狀態(tài)碼。返回的消息體中是具體的錯(cuò)誤代碼及錯(cuò)誤信息。 另外還包含一個(gè)全局唯一的請(qǐng)求ID：RequestId和一個(gè)您該次請(qǐng)求訪問(wèn)的站點(diǎn)ID：HostId。在調(diào)用方找不到錯(cuò) 誤原因時(shí)，可以聯(lián)系阿里云客服，并提供該HostId和RequestId，以便我們盡快幫您解決問(wèn)題。8906582E-6722-409A-A6C4-0E7863B733A5InvalidTemplate

10、.NotFoundThe specified template does not found.JSON示例RequestId: 8906582E-6722-409A-A6C4-0E7863B733A5,HostId: ,Code: InvalidTemplate.NotFound,Message: The specified template does not found.簽名機(jī)制（注：若使用sdk無(wú)需查看簽名機(jī)制。當(dāng)前已提供java、php、C#的sdk。接口支持GET和POST提交,但是GET和POST的StringToSign不一樣.）DirectMail 服務(wù)會(huì)對(duì)每個(gè)訪問(wèn)的請(qǐng)求進(jìn)行身份

11、驗(yàn)證，所以無(wú)論使用 HTTP 還是 HTTPS 協(xié)議提交請(qǐng)求，都需要在請(qǐng)求中包含簽名（Signature）信息。DirectMailAccessKeyIDAccessKeySecretKeyIDAccessKeySecret（可以通過(guò)阿里云官方網(wǎng)站申請(qǐng)和管理），AccessKeyID；AccessKeySecret用戶在訪問(wèn)時(shí)，按照下面的方法對(duì)請(qǐng)求進(jìn)行簽名處理：使用請(qǐng)求參數(shù)構(gòu)造規(guī)范化的請(qǐng)求字符串（Canonicalized Query String）按照參數(shù)名稱的字典順序?qū)φ?qǐng)求中所有的請(qǐng)求參數(shù)（包括文檔中描述的公共請(qǐng)求參數(shù)和給定了的 Signature）進(jìn)行排序。注：當(dāng)使用 GET 方法提交請(qǐng)

12、求時(shí)，這些參數(shù)就是請(qǐng)求 URI 中的參數(shù)部分（即 URI中?之后由&連接的部分）。A-Z、a-z、0-9_、.、不編碼;對(duì)于其他字符編碼成%XYXYA-Z、a-z、0-9_、.、不編碼;對(duì)于其他字符編碼成%XYXYASCII16進(jìn)制表示。比如英文的雙引號(hào)（）對(duì)應(yīng)的編碼就是%22UTF-8%XY%ZA的格式;需要說(shuō)明的是英文空格（）要被編碼是%20，而不是加號(hào)（+）。注：一般支持 URL 編碼的庫(kù)（比如 Java 中的 .URLEncoder）都是按照application/x- www-form-urlencoded的MIME類型的規(guī)則進(jìn)行編碼的。實(shí)現(xiàn)時(shí)可以直接使用這類方式進(jìn)行編碼，把編碼后的

13、字符串中加號(hào)（+）替換成%20、星號(hào)（*）替換成%2A、%7E 替換回波浪號(hào)（），即可得到上述規(guī)則描述的編碼字符串。對(duì)編碼后的參數(shù)名稱和值使用英文等號(hào)（=）進(jìn)行連接。再把英文等號(hào)連接得到的字符串按參數(shù)名稱的字典順序依次使用&符號(hào)連接，即得到規(guī)范化請(qǐng)求 字符串。StringToSign= HTTPMethod + & + percentEncode(/) + & +percentEncode(CanonicalizedQueryString)StringToSign= HTTPMethod + & + percentEncode(/) + & +percentEncode(Canonicaliz

14、edQueryString)其中 HTTPMethod 是提交請(qǐng)求用的 HTTP 方法，比 GET、POST。percentEncode(/)是按照 1.b 中描述的 URL 編碼規(guī)則對(duì)字符/進(jìn)行編碼得到的值，即%2F。percentEncode(CanonicalizedQueryString)是對(duì)第 1 步中構(gòu)造的規(guī)范化請(qǐng)求字符串按 1.b 中描述的 URL 編碼規(guī)則編碼后得到的字符串。按照 RFC2104 的定義，使用上面的用于簽名的字符串計(jì)算簽名 HMAC 值。注意：計(jì)算簽名時(shí)使用KeyAccessKeySecret&字符(ASCII:38)，使用的哈希算法是SHA1。Base64HM

15、AC（Signature）。將得到的簽名值作為 Signature 參數(shù)添加到請(qǐng)求參數(shù)中，即完成對(duì)請(qǐng)求簽名的過(guò)程。 注意：得到的簽名值在作為最后的請(qǐng)求參數(shù)值提交給 DirectMail 服務(wù)器的時(shí)候，要和其他 參數(shù)一樣，按照RFC3986 的規(guī)則進(jìn)行 URL 編碼）。以 SingleSendMail接口為例，通過(guò)HTTPS發(fā)送POST請(qǐng)求調(diào)用說(shuō)明為例：請(qǐng)求 URL 為： HYPERLINK / / 參數(shù)為AccessKeyId=testid&AccountName=1&Action=SingleSendMail&AddressType=1&Format=xml&HtmlBody=4&Repl

16、AccessKeyId=testid&AccountName=1&Action=SingleSendMail&AddressType=1&Format=xml&HtmlBody=4&Repl yToAddress=true&SignatureMethod=Hmac-SHA1&SignatureNonce=e1b44502-6d13-4433-9493- 69eeb068e955&SignatureVersion=1.0&Subject=3&TagName=2&Timestamp=2015-11- 24T05%3A06%3A00Z&ToAddress=1%40&Version=2015-11-2

17、3那么 StringToSign 就是POST&%2F&AccessKeyId%3Dtestid%26AccountName%3D1%26Action%3DSingleSendMail%26AddressType%3D1% 26Format%3Dxml%26HtmlBody%3D4%26ReplyToAddress%3Dtrue%26SignatureMethod%3DHmac- SHA1%26SignatureNonce%3De1b44502-6d13-4433-9493- 69eeb068e955%26SignatureVersion%3D1.0%26Subject%3D3%26TagNa

18、me%3D2%26Timestamp%3D2015-11- 24T05%253A06%253A00Z%26ToAddress%3D1%2540%26Version%3D2015-11-23Access Key Idtestid，Access Key Secrettestsecret，HMACKey1ohA2le%2BLu4D05AM3MFrI8nJZQs%3D1ohA2le%2BLu4D05AM3MFrI8nJZQs%3DSignature=1ohA2le%2BLu4D05AM3MFrI8nJZQs%3D&Format=xml&Subject=3&HtmlBody=4&SignatureMet

19、hod=H mac-SHA1&Timestamp=2015-11- 24T05%3A06%3A00Z&TagName=2&Action=SingleSendMail&AccessKeyId=testid&AccountName=1&ReplyToAddr ess=true&AddressType=1&SignatureNonce=e1b44502-6d13-4433-9493- 69eeb068e955&SignatureVersion=1.0&Version=2015-11-23&ToAddress=1%40簽名后的請(qǐng)求 Signature=1ohA2le%2BLu4D05AM3MFrI8n

20、JZQs%3D&Format=xml&Subject=3&HtmlBody=4&SignatureMethod=H mac-SHA1&Timestamp=2015-11- 24T05%3A06%3A00Z&TagName=2&Action=SingleSendMail&AccessKeyId=testid&AccountName=1&ReplyToAddr ess=true&AddressType=1&SignatureNonce=e1b44502-6d13-4433-9493- 69eeb068e955&SignatureVersion=1.0&Version=2015-11-23&ToAd

21、dress=1%40發(fā)信郵件相關(guān)接口單一發(fā)信接口描述請(qǐng)求參數(shù)名稱類型是否必須描述ActionString必須操作接口名，系統(tǒng)規(guī)定參數(shù)，取值：SingleSendMailAccountNameString必須管理控制臺(tái)中配置的發(fā)信地址ReplyToAddressBoolean必須是否使用管理控制臺(tái)中配置的回信地址（狀態(tài)必須是驗(yàn)證通過(guò)）AddressTypeNumber必須取值范圍01: 0為隨機(jī)賬號(hào)(推薦,可以更好的統(tǒng)計(jì)退信情況);1為發(fā)信地址ToAddressString必須目標(biāo)地址，多個(gè)Email地址可以逗號(hào)分隔FromAliasString可選發(fā)信人昵稱,長(zhǎng)度小于15個(gè)字符 例如:發(fā)信人昵

22、稱設(shè)置為小紅，發(fā)信地址為 HYPERLINK mailto:test test，收信人看到的發(fā)信地址為小紅 HYPERLINK mailto:testexample.co SubjectString可選郵件主題,建議填寫HtmlBodyString可選郵件html正文TextBodyString可選郵件text正文其他請(qǐng)求參數(shù)請(qǐng)參見(jiàn) 公共請(qǐng)求參數(shù)返回參數(shù)公共返回參數(shù)，詳見(jiàn)公共返回參數(shù)錯(cuò)誤碼錯(cuò)誤代碼描述Http狀態(tài)碼語(yǔ)義InvalidMailAddress. NotFoundThe specified mailAddress does not exist.400發(fā)信地址不存在InvalidMai

23、lAddressStThe specified400發(fā)信地址狀態(tài)不正確atus.MalformedmailAddress status is wrongly formed.InvalidToAddressThe specified toAddress is wrongly formed.400目標(biāo)地址不正確。目標(biāo)地 址 不 是 正 確 的 Email或者超過(guò)1000個(gè)上限InvalidBodyThe specified textBody or htmlBody is wrongly formed.400郵件正文不正確。textBody 或htmlBody不能同時(shí)為空InvalidSendMai

24、l.Spa mSendmail rejected by spam filter.400本次發(fā)送操作被反垃圾系統(tǒng)檢測(cè)為垃圾郵件，禁止發(fā)送。請(qǐng)仔細(xì)檢查郵件內(nèi)容和域名狀態(tài)等InvalidSubject.Malfo rmedThe specified subject is wrongly formed.400郵件主題限制在100個(gè)字符以內(nèi)InvalidMailAddressD omain.MalformedThe specified mailAddress domain does not exist.400發(fā)信地址的域名狀態(tài)不正確，請(qǐng)檢查MX、SPF配置是否正確示例/?Action=SingleSen

25、dMail HYPERLINK mailto:%26AccountName%3Dtest &AccountName=test &ReplyToAddress=true/?Action=SingleSendMail HYPERLINK mailto:%26AccountName%3Dtest &AccountName=test &ReplyToAddress=true&AddressType=1 HYPERLINK mailto:%26ToAddress%3Dtest1 &Subject=Subject &HtmlBody=body &返回示例12D086F6-8F31-4658-84C1-00

26、6DED011A85XML格式12D086F6-8F31-4658-84C1-006DED011A85JSON示例RequestId: 12D086F6-8F31-4658-84C1-006DED011A85批量發(fā)信接口描述請(qǐng)求參數(shù)名稱類型是否必須描述ActionString是操作接口名，系統(tǒng)規(guī)定參數(shù)，取值：BatchSendMailAccountNameString必須管理控制臺(tái)中配置的發(fā)信地址AddressTypeNumber必須取值范圍01: 0為隨機(jī)賬號(hào)(推薦,可以更好的統(tǒng)計(jì)退信情況);1為發(fā)信地址TemplateNameString必須預(yù)先創(chuàng)建且通過(guò)審核的模板名稱ReceiversN

27、ameString必須預(yù)先創(chuàng)建且上傳了收件人的收件人列表名稱TagNameString可選郵件標(biāo)簽名稱其他請(qǐng)求參數(shù)請(qǐng)參見(jiàn) 公共請(qǐng)求參數(shù)返回參數(shù)公共返回參數(shù)，詳見(jiàn)公共返回參數(shù)錯(cuò)誤碼錯(cuò)誤代碼描述Http狀態(tài)碼語(yǔ)義InvalidMailAddress. NotFoundThe specified mailAddress does not exist.400發(fā)信地址不存在InvalidMailAddressStThe specified400發(fā)信地址狀態(tài)不正確atus.MalformedmailAddress status is wrongly formed.InvalidMailAddressS e

28、ndType.MalformedThe specified mailAddress sendType is wrongly formed.400郵件地址類型不正確，只能使用類型為批量的郵件地址目標(biāo)地址不正確。目標(biāo)地址不是正確的Email或者超過(guò)1000個(gè)上限InvalidReceiverNam e.MalformedThe specified receiver name is wrongly formed.400收件人列表名稱不正確。列表不存在或者列表為空InvalidSendMail.Spa mSendmail rejected by spam filter.400本次發(fā)送操作被反垃圾系統(tǒng)檢

29、測(cè)為垃圾郵件，禁止發(fā)送。請(qǐng)仔細(xì)檢查郵件內(nèi)容和域名狀態(tài)等InvalidTemplateNam e.MalformedThe specified template name is wrongly formed.400模板名稱不正確。InvalidMailAddressD omain.MalformedThe specified mailAddress domain does not exist.400發(fā)信地址的域名狀態(tài)不正確，請(qǐng)檢查MX、SPF配置是否正確示例/?Action=BatchSendMail HYPERLINK mailto:%26AccountName%3Dtest /?Action

30、=BatchSendMail HYPERLINK mailto:%26AccountName%3Dtest &AccountName=test &AddressType=1&TagName=test3 &返回示例12D086F6-8F31-4658-84C1-006DED011A8512D086F6-8F31-4658-84C1-006DED011A85JSON示例RequestId: 12D086F6-8F31-4658-84C1-006DED011A85發(fā)送短信相關(guān)接口單一發(fā)短信接口描述請(qǐng)求參數(shù)名稱類型是否必須描述ActionString必須操作接口名，系統(tǒng)規(guī)定參數(shù)，取值：SingleSe

31、ndSmsSignNameString必須管理控制臺(tái)中配置的短信簽名（狀態(tài)必須是驗(yàn)證通過(guò)）TemplateCodeString必須管理控制臺(tái)中配置的審核通過(guò)的短信模板的模板CODE（狀態(tài)必須是驗(yàn)證通過(guò)）RecNumString必須目標(biāo)手機(jī)號(hào)，多個(gè)手機(jī)號(hào)可以逗號(hào)分隔ParamStringString必選短信模板中的變量，個(gè)人用戶每個(gè)變量長(zhǎng)度必須小于15個(gè)字符 例如:短信模板為：接受短信驗(yàn)證碼$no,此參數(shù)傳遞no:123456，用戶將接收到短信簽名接受短信驗(yàn)證碼123456其他請(qǐng)求參數(shù)請(qǐng)參見(jiàn) 公共請(qǐng)求參數(shù)返回參數(shù)公共返回參數(shù)，詳見(jiàn) 公共請(qǐng)求參數(shù)錯(cuò)誤碼錯(cuò)誤代碼描述Http狀態(tài)碼語(yǔ)義InvalidDayuStatus.M alformedThe specified dayu status is wrongly formed.400賬戶短信開(kāi)通狀態(tài)不正確InvalidSignName.Ma lformedThe specified sign name is wrongly formed.400短信簽名不正確或簽名狀態(tài)不正確InvalidTemplateCod e.MalFormedThe specified templateCod