阿里云郵件推送服務(wù)-API參考-D

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

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

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

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

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

6、0SignatureNonceString是唯一隨機數(shù)，用于防止網(wǎng)絡(luò)重放攻擊。用戶在不同請求間要使用不同的隨機數(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)用請求，無論成功與否，系統(tǒng)都會返回一個唯一識別碼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ù)后返回數(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)可以在請求時傳入?yún)?shù)來制定 返回的數(shù)據(jù)格式，默認(rèn)為XML格式。本文檔中的返回示例為了便于用戶查看，做了格式化處理，實際返回結(jié)果 是沒有進行換行、縮進等處理的。成功結(jié)果4C467B38-3910-447D-87BC-AC049166F216JSON示例RequestId: 4C467B38-3910-447D-87BC

9、-AC049166F216/* 返回結(jié)果數(shù)據(jù) */錯誤結(jié)果調(diào)用接口出錯后，將不會返回結(jié)果數(shù)據(jù)。調(diào)用方可根據(jù)每個接口對應(yīng)的錯誤碼以及下述2.3.3的公共錯誤碼來定 位錯誤原因。當(dāng)調(diào)用出錯時，HTTP請求返回一個4xx或5xx的HTTP狀態(tài)碼。返回的消息體中是具體的錯誤代碼及錯誤信息。 另外還包含一個全局唯一的請求ID：RequestId和一個您該次請求訪問的站點ID：HostId。在調(diào)用方找不到錯 誤原因時，可以聯(lián)系阿里云客服，并提供該HostId和RequestId，以便我們盡快幫您解決問題。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.簽名機制（注：若使用sdk無需查看簽名機制。當(dāng)前已提供java、php、C#的sdk。接口支持GET和POST提交,但是GET和POST的StringToSign不一樣.）DirectMail 服務(wù)會對每個訪問的請求進行身份

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

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

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

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

15、AC（Signature）。將得到的簽名值作為 Signature 參數(shù)添加到請求參數(shù)中，即完成對請求簽名的過程。 注意：得到的簽名值在作為最后的請求參數(shù)值提交給 DirectMail 服務(wù)器的時候，要和其他 參數(shù)一樣，按照RFC3986 的規(guī)則進行 URL 編碼）。以 SingleSendMail接口為例，通過HTTPS發(fā)送POST請求調(diào)用說明為例：請求 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簽名后的請求 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ā)信接口描述請求參數(shù)名稱類型是否必須描述ActionString必須操作接口名，系統(tǒng)規(guī)定參數(shù)，取值：SingleSendMailAccountNameString必須管理控制臺中配置的發(fā)信地址ReplyToAddressBoolean必須是否使用管理控制臺中配置的回信地址（狀態(tài)必須是驗證通過）AddressTypeNumber必須取值范圍01: 0為隨機賬號(推薦,可以更好的統(tǒng)計退信情況);1為發(fā)信地址ToAddressString必須目標(biāo)地址，多個Email地址可以逗號分隔FromAliasString可選發(fā)信人昵稱,長度小于15個字符 例如:發(fā)信人昵

22、稱設(shè)置為小紅，發(fā)信地址為 HYPERLINK mailto:test test，收信人看到的發(fā)信地址為小紅 HYPERLINK mailto:testexample.co SubjectString可選郵件主題,建議填寫HtmlBodyString可選郵件html正文TextBodyString可選郵件text正文其他請求參數(shù)請參見 公共請求參數(shù)返回參數(shù)公共返回參數(shù)，詳見公共返回參數(shù)錯誤碼錯誤代碼描述Http狀態(tài)碼語義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或者超過1000個上限InvalidBodyThe specified textBody or htmlBody is wrongly formed.400郵件正文不正確。textBody 或htmlBody不能同時為空InvalidSendMai

24、l.Spa mSendmail rejected by spam filter.400本次發(fā)送操作被反垃圾系統(tǒng)檢測為垃圾郵件，禁止發(fā)送。請仔細檢查郵件內(nèi)容和域名狀態(tài)等InvalidSubject.Malfo rmedThe specified subject is wrongly formed.400郵件主題限制在100個字符以內(nèi)InvalidMailAddressD omain.MalformedThe specified mailAddress domain does not exist.400發(fā)信地址的域名狀態(tài)不正確，請檢查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ā)信接口描述請求參數(shù)名稱類型是否必須描述ActionString是操作接口名，系統(tǒng)規(guī)定參數(shù)，取值：BatchSendMailAccountNameString必須管理控制臺中配置的發(fā)信地址AddressTypeNumber必須取值范圍01: 0為隨機賬號(推薦,可以更好的統(tǒng)計退信情況);1為發(fā)信地址TemplateNameString必須預(yù)先創(chuàng)建且通過審核的模板名稱ReceiversN

27、ameString必須預(yù)先創(chuàng)建且上傳了收件人的收件人列表名稱TagNameString可選郵件標(biāo)簽名稱其他請求參數(shù)請參見 公共請求參數(shù)返回參數(shù)公共返回參數(shù)，詳見公共返回參數(shù)錯誤碼錯誤代碼描述Http狀態(tài)碼語義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或者超過1000個上限InvalidReceiverNam e.MalformedThe specified receiver name is wrongly formed.400收件人列表名稱不正確。列表不存在或者列表為空InvalidSendMail.Spa mSendmail rejected by spam filter.400本次發(fā)送操作被反垃圾系統(tǒng)檢

29、測為垃圾郵件，禁止發(fā)送。請仔細檢查郵件內(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)不正確，請檢查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ā)短信接口描述請求參數(shù)名稱類型是否必須描述ActionString必須操作接口名，系統(tǒng)規(guī)定參數(shù)，取值：SingleSe

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