Surenotify API 文件
API Endpoint
https://mail.surenotifyapi.comOverview ¶
電子豹 Surenotify 推出的通知(Transactional)型 API,讓開發者可透過 API 操作的方式,完成像是帳號啟用信、忘記密碼信、購物車未結帳等系統觸發通知信用途,提供更即時的顧客服務體驗。 Surenotify API 主要分成四個部分:
-
寄信服務
-
數據追蹤服務
-
寄送狀態查證服務
-
數位簽章設定服務
各項服務的 API 使用說明,請參閱章節內文,有任何問題皆歡迎來信詢問。
-
客服時間:週一~五 09:30-12:00 / 13:30-18:00
身份驗證
-
進行 API 連線時,必須在 request header 中帶入驗證資訊:
key value x-api-key
金鑰內容 -
若沒有帶入驗證資訊,或是金鑰內容有誤,將會回傳:
{"message": "Forbidden"}
-
如何申請 API KEY?
- Step1:註冊電子豹帳號
- Step2:寄信至 technical_support@newsleopard.com ,信件請註名
申請 Surenotify 測試 API KEY
,並附上註冊帳號
,開通後將會回信通知
寄信服務 ¶
信件變數使用說明
用途說明
於信件中使用 recipient 的 variables 欄位來完成客製化信件之功能。
範例
以下為系統帳號啟用信的範例:
<html>
<body>
<h2>{{account}} 你好,</h2>
<div>請點擊下方按鈕以完成 Email 驗證,驗證後即可回到原本的頁面繼續操作。</div>
<a href="https://api-sample.newsleopard.com/account/activation?id={{systemId}}&signature={{signature}}">驗證Email信箱</a>
</body>
</html>
假設信件透過下面的 request 範例分別寄給 Alice 及 Bob
{
"subject": "{{nickname}}, 快來開通啟用你的電子豹帳號",
"fromName": "豹小編",
"fromAddress": "no-replay@newsleopard.com",
"content": "<html> <body> <h2>{{account}} 你好,</h2> <div>請點擊下方按鈕以完成 Email 驗證,驗證後即可回到原本的頁面繼續操作。</div> <a href=\"https://api-sample.newsleopard.com/account/activation?id={{systemId}}&signature={{signature}}\">驗證Email信箱</a> </body> </html>",
"unsubscribedLink": "https://links.to.your.unsubscribe.link",
"recipients": [
{
"name": "bob",
"address": "bob@gmail.com",
"variables": {
"nickname": "Mr.B",
"account": "bob@gmail.com",
"systemId": "1234-56-78-9012",
"signature": "Ym9iQGdtYWlsLmNvbQ=="
}
},
{
"name": "alice",
"address": "alice@hotmail.com",
"variables": {
"nickname": "Alice",
"account": "alice@hotmail.com",
"systemId": "9012-34-56-7890",
"signature": "YWxpY2VAaG90bWFpbC5jb20="
}
}
]
}
Alice 收到的信件主旨會是 Alice, 快來開通啟用你的電子豹帳號
信件內容文字會被替換成 alice@hotmail.com 你好, 請點擊下方按鈕以完成 Email 驗證,驗證後即可回到原本的頁面繼續操作。
信件內的驗證信箱連結將會被系統替換,當 Alice 點擊後會將 Alice 轉導至 https://api-sample.newsleopard.com/account/activation?id=9012-34-56-7890&signature=YWxpY2VAaG90bWFpbC5jb20%3D
同理,Bob 收到的信件主旨會是 Mr.B, 快來開通啟用你的電子豹帳號
信件內容文字會被替換成 bob@gmail.com 你好, 請點擊下方按鈕以完成 Email 驗證,驗證後即可回到原本的頁面繼續操作。
信件內的驗證信箱連結將會被系統替換,當 Bob 點擊後會將 Bob 轉導至 https://api-sample.newsleopard.com/account/activation?id=1234-56-78-9012&signature=Ym9iQGdtYWlsLmNvbQ%3D%3D
單筆/多筆寄信 ¶
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
"subject": "系統通知信",
"fromName": "豹小編",
"fromAddress": "bao@newsleopard.com",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"unsubscribedLink": "https://links.to.your.unsubscribe.link",
"recipients": [
{
"name": "bob",
"address": "bob@gmail.com",
"variables": {
"UUID": "1234-56-78-9012"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"fromName": {
"type": "string",
"description": "寄件人名稱"
},
"fromAddress": {
"type": "string",
"description": "寄件人email"
},
"content": {
"type": "string",
"description": "信件內容"
},
"unsubscribedLink": {
"type": "string",
"description": "取消訂閱連結, 將顯示於收件軟體的標題中"
},
"recipients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "收件人姓名"
},
"address": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"UUID": {
"type": "string"
}
}
}
},
"required": [
"address"
]
}
}
},
"required": [
"subject",
"fromAddress",
"content"
]
}
Headers
Content-Type: application/json
Body
{
"id": "7897e18f-19bc-44eb-9149-e95e9ffc5d27",
"success": [
{
"id": "20191107080336-47f09d97-9a46-4215-bdb7-de68eca1c436",
"address": "bob@gmail.com"
}
],
"failure": {}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"allOf": [
{
"$ref": "#/definitions/id"
},
{
"$ref": "#/definitions/success"
},
{
"$ref": "#/definitions/failure"
}
],
"definitions": {
"id": {
"type": "object",
"patternProperties": {
"": {
"type": "string"
}
}
},
"success": {
"type": "object",
"patternProperties": {
"": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"address": {
"type": "string"
}
}
}
}
}
},
"failure": {
"type": "object",
"patternProperties": {
"": {
"type": "object",
"properties": {}
}
}
}
}
}
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
"subject": "系統通知信",
"fromName": "豹小編",
"fromAddress": "bao@newsleopard.com",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"unsubscribedLink": "https://links.to.your.unsubscribe.link",
"recipients": [
{
"name": "alice",
"address": "alice@yahoo.com.tw",
"variables": {
"gender": "woman"
}
},
{
"name": "bob",
"address": "bob@gmail.com",
"variables": {
"gender": "man"
}
},
{
"name": "iamnotanemail",
"address": "iamnotanemail",
"variables": {}
},
{
"name": "variable_too_long",
"address": "variable_too_long@gmail.com",
"variables": {
"description": [
"i_am_the_variable_whose_length_is_over_100_characeters_Lorem",
"ipsum dolor sit amet consectetur adipisicing elit. Quis quaerat quas",
"architecto magni id minima labore illum eligendi impedit numquam debitis. Recusandae eos placeat dolorum. Aliquam obcaecati delectus adipisci molestias?"
]
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"fromName": {
"type": "string",
"description": "寄件人名稱"
},
"fromAddress": {
"type": "string",
"description": "寄件人email"
},
"content": {
"type": "string",
"description": "信件內容"
},
"unsubscribedLink": {
"type": "string",
"description": "取消訂閱連結, 將顯示於收件軟體的標題中"
},
"recipients": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "收件人姓名"
},
"address": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"gender": {
"type": "string"
}
}
}
},
"required": [
"address"
]
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "收件人姓名"
},
"address": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"gender": {
"type": "string"
}
}
}
},
"required": [
"address"
]
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "收件人姓名"
},
"address": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {}
}
},
"required": [
"address"
]
},
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "收件人姓名"
},
"address": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"description": {
"type": "array"
}
}
}
},
"required": [
"address"
]
}
]
}
},
"required": [
"subject",
"fromAddress",
"content"
]
}
Headers
Content-Type: application/json
Body
{
"id": "7897e18f-19bc-44eb-9149-e95e9ffc5d27",
"success": [
{
"id": "20191107080336-4ca1d97-216e-4a2b-b7ad-68deeac1c1ca6",
"address": "alice@yahoo.com.tw"
},
{
"id": "20191107080336-47f09d97-9a46-4215-bdb7-de68eca1c436",
"address": "bob@gmail.com"
}
],
"failure": {
"iamnotanemail": "Invalid: address is not a valid email format",
"too_many_variables@gmail.com": "Invalid: the amount of recipient variables should under 10",
"variable_too_long@gmail.com": "Invalid: the value of recipient variables should under 100 characters"
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"allOf": [
{
"$ref": "#/definitions/id"
},
{
"$ref": "#/definitions/success"
},
{
"$ref": "#/definitions/failure"
}
],
"definitions": {
"id": {
"type": "object",
"patternProperties": {
"": {
"type": "string"
}
}
},
"success": {
"type": "object",
"patternProperties": {
"": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"address": {
"type": "string"
}
}
},
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"address": {
"type": "string"
}
}
}
]
}
}
},
"failure": {
"type": "object",
"patternProperties": {
"": {
"type": "object",
"properties": {
"iamnotanemail": {
"type": "string"
},
"too_many_variables@gmail.com": {
"type": "string"
},
"variable_too_long@gmail.com": {
"type": "string"
}
}
}
}
}
}
}
Headers
Content-Type: application/json
Body
{
"message": "Invalid request body",
"errors": "[ array is too long: must have at most 100 elements ]"
}
單筆/多筆寄信POST/v1/messages
用途說明
透過本服務進行 EMAIL 單筆或多筆之寄送,並可透過變數的使用 (請參考: 信件變數使用說明),以達到個人化信件之效果。
Request 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
subject * |
string |
信件主旨 |
fromName |
string |
寄件人姓名,若未給值,系統將使用 fromAddress 的名稱,例如:technical_support@newsleopard.com 中的 service 作為寄件人姓名 |
fromAddress * |
string |
寄件人Email |
content * |
string |
信件html內容 |
unsubscribedLink |
string |
取消訂閱連結,讓收件人能夠取消訂閱,參考MIME Spec ,將顯示於收件軟體的標題中 |
recipients * |
array |
收件人,最多放置 100 recipient / request |
recipients.name * |
string |
收件人姓名 |
recipients.address * |
string |
收件人Email |
recipients.variables |
object |
收件人的變數,自定義,每個 variables 內容長度最長 100。使用方式請參考:信件變數使用說明 |
* 必填欄位
Response 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
id |
string |
request ID |
success.id |
string |
信件 ID |
success.address |
string |
收件人Email |
failure |
object |
收件人錯誤,類型如下: ・Email 格式不符:Invalid: address is not a valid email format ・收件人變數內容過長:Invalid: the value of recipient variables should under 100 characters |
數據追蹤服務 ¶
Webhook 回傳事件說明
用途說明
提供 Email 行為事件追蹤服務,並透過 Webhook 的方式,即時將相關事件回傳,包括:delivery(到達)、open(開信)、click(點擊)、bounce(退信)、complaint(抱怨)。
回傳方式
以 HTTP POST 方式傳送至使用者設定的 URL
Signature 驗證
為了確保 request 是由 電子豹 Surenotify 所發出,使用者可以驗證 request header 內的 x-surenotify-signature 來確認是否由本服務所發出
- 驗證步驟:
{ "event": "delivery", "mail": { "id": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7", } }
- 取得 Surenotify 回傳 header 內的 x-surenotify-signature
- 取得 body 內 mail id 與 event (mailId , eventType)
- 將 mailId 與 eventType 組成字串
- 例: message =
"20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7delivery"
- 例: message =
- 將 API key (x-api-key) 設為 secret key 以 HmacSHA256 將 message 加密產生 Hex 字串 (signature)
- 比對 header 內的 x-surenotify-signature 與 計算出的 signature 是否相等
回傳事件欄位說明
欄位 | 型別 | 說明 |
---|---|---|
event |
string |
事件類型,分別為: ・delivery(到達) ・open(開信) ・click(點擊) ・bounce(退信) ・complaint(抱怨) |
id |
string |
信件 ID |
subject |
string |
信件主旨 |
content |
string |
信件內容 |
from |
string |
寄件人 |
to |
string |
收件人 |
variables |
object |
收件人的變數 |
delivery.timestamp |
string |
到達時間 |
open.timestamp |
string |
開信時間 |
open.client_headers |
string |
收件人的表頭資訊 |
click.timestamp |
string |
點擊時間 |
click.sort |
string |
連結順序,按照信件內容的連結順序排序,0 表示第一個,以此類推 |
click.link_url |
string |
點擊網址 |
click.client_headers |
string |
收件人的表頭資訊 |
bounce.timestamp |
string |
退信時間 |
bounce.code |
string |
SMTP code |
bounce.type |
number |
退信類型,0:暫時退信;1:永久退信 |
bounce.reason |
string |
退信原因 |
complaint.timestamp |
string |
抱怨時間 |
範例:
delivery(到達)
{
"event": "delivery",
"mail": {
"id": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"subject": "系統通知信",
"content": "",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"variables": {
"UUID": "1234-56-78-9012"
},
},
"delivery": {
"timestamp": "1577836800000"
}
}
open(開信)
{
"event": "open",
"mail": {
"id": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"subject": "系統通知信",
"content": "",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"variables": {
"UUID": "1234-56-78-9012"
},
},
"open": {
"timestamp": "1577836800000",
"client_headers": "{Accept=image/png,image/svg+xml,image/*;q=0.8,video/*;q=0.8,*/*;q=0.5, Accept-Encoding=br, gzip, deflate, Accept-Language=en-us, CloudFront-Forwarded-Proto=https, CloudFront-Is-Desktop-Viewer=true, CloudFront-Is-Mobile-Viewer=false, CloudFront-Is-SmartTV-Viewer=false, CloudFront-Is-Tablet-Viewer=false, CloudFront-Viewer-Country=HK, Host=mail.surenotifyapi.com, Referer=https://outlook.live.com/, User-Agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1 Safari/605.1.15, Via=2.0 632ca9875c25dbcff60b54139f83cb7a.cloudfront.net (CloudFront), X-Amz-Cf-Id=nOTGJmuDsy7LYnSma1kDmDvp-tpkNtibo9pRaRvcwP-xJsfvKYnnrw==, X-Amzn-Trace-Id=Root=1-5ed33920-c6e20b989a5e0ddc092e726c, X-Forwarded-For=192.168.0.0, 192.168.0.1, X-Forwarded-Port=443, X-Forwarded-Proto=https}"
}
}
click(點擊)
{
"event": "click",
"mail": {
"id": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"subject": "系統通知信",
"content": "",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"variables": {
"UUID": "1234-56-78-9012"
},
},
"click": {
"timestamp": "1577836800000",
"sort": "0",
"link_url": "https://example.com",
"client_headers": "{Accept=image/png,image/svg+xml,image/*;q=0.8,video/*;q=0.8,*/*;q=0.5, Accept-Encoding=br, gzip, deflate, Accept-Language=en-us, CloudFront-Forwarded-Proto=https, CloudFront-Is-Desktop-Viewer=true, CloudFront-Is-Mobile-Viewer=false, CloudFront-Is-SmartTV-Viewer=false, CloudFront-Is-Tablet-Viewer=false, CloudFront-Viewer-Country=HK, Host=mail.surenotifyapi.com, Referer=https://outlook.live.com/, User-Agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1 Safari/605.1.15, Via=2.0 632ca9875c25dbcff60b54139f83cb7a.cloudfront.net (CloudFront), X-Amz-Cf-Id=nOTGJmuDsy7LYnSma1kDmDvp-tpkNtibo9pRaRvcwP-xJsfvKYnnrw==, X-Amzn-Trace-Id=Root=1-5ed33920-c6e20b989a5e0ddc092e726c, X-Forwarded-For=192.168.0.0, 192.168.0.1, X-Forwarded-Port=443, X-Forwarded-Proto=https}"
}
}
bounce(退信)
{
"event": "bounce",
"mail": {
"id": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"subject": "系統通知信",
"content": "",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"variables": {
"UUID": "1234-56-78-9012"
},
},
"bounce": {
"timestamp": "1577836800000",
"code": "5.0.0",
"type": "1",
"reason": "system: user unknown",
}
}
complaint(抱怨)
{
"event": "complaint",
"mail": {
"id": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"subject": "系統通知信",
"content": "",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"variables": {
"UUID": "1234-56-78-9012"
},
},
"complaint": {
"timestamp": "1577836800000"
}
}
備註
鑒於每家 mail server 回應的時間不盡相同,Surenotify 設計上,寄信寄出即先定義為 delivery,故有可能收到 delivery 事件後,又收到 bounce 事件的情況,請注意。
新增/修改 Webhook ¶
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
"type": 3,
"url": "https://urwebhook.com"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "事件類型"
},
"url": {
"type": "string",
"description": "webhook位址"
}
},
"required": [
"type"
]
}
Headers
Content-Type: application/json
Body
{
"success": true
}
Headers
Content-Type: application/json
Body
{
"success": false,
"messages": [
"Invalid: type is not a valid value."
]
}
新增/修改 WebhookPOST/v1/webhooks
用途說明
本服務讓你可自行設定欲即時接收的事件 Webhook URL,以確認每封信件的寄送狀態,包括:delivery(到達)、open(開信)、click(點擊)、bounce(退信)、complaint(抱怨)。
Request 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
type * |
number |
事件類型代碼,分別為: ・delivery(到達):3 ・open(開信):4 ・click(點擊):5 ・bounce(退信):6 ・complaint(抱怨):7 |
url * |
string |
Webhook 註冊網址 |
* 必填欄位
Response 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
success |
boolean |
新增成功與否,ture 或 false |
message |
array |
新增失敗原因 |
備註
當新增的 type url紀錄不存在時,會新增資料;反之,則會修改原有紀錄
查詢 Webhook ¶
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"type": 3,
"domain": "default",
"url": "https://urwebhook.com",
"createDate": "2019-03-05T08:19:26Z"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "number",
"description": "事件類型"
},
"domain": {
"type": "string",
"description": "網域名稱"
},
"url": {
"type": "string",
"description": "webhook位址"
},
"createDate": {
"type": "string",
"description": "建立時間"
}
},
"required": [
"type"
]
}
查詢 WebhookGET/v1/webhooks
用途說明
本服務讓你可查詢目前已設定的所有 Webhook 內容。
Response 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
type |
number |
事件類型代碼,分別為: ・delivery(到達):3 ・open(開信):4 ・click(點擊):5 ・bounce(退信):6 ・complaint(抱怨):7 |
domain |
string |
網域名稱 |
url |
string |
Webhook 註冊網址 |
createDate |
string |
建立時間 |
刪除 Webhook ¶
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
"type": 3
}
Headers
Content-Type: application/json
Body
{
"success": true,
}
Headers
Content-Type: application/json
Body
{
"success": false,
}
刪除 WebhookDELETE/v1/webhooks
用途說明
本服務讓你可刪除目前已設定的 Webhook 內容。
Request 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
type * |
number |
事件類型代碼,分別為: ・delivery(到達):3 ・open(開信):4 ・click(點擊):5 ・bounce(退信):6 ・complaint(抱怨):7 |
* 必填欄位
Response 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
success |
boolean |
刪除成功與否,ture 或 false |
寄送狀態查證服務 ¶
事件查詢 ¶
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"logs": [
{
"messageId": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"status": "accept",
"mail": {
"subject": "系統通知信",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"sender": "bao@newsleopard.com",
"recipient": "bob@gmail.com",
"variables": {
"UUID": "1234-56-78-9012"
}
},
"eventTime": "2019-12-15T08:38:32Z",
"rawEvent": {}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "信件ID"
},
"status": {
"type": "string",
"description": "事件類型"
},
"mail": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"content": {
"type": "string",
"description": "信件內容"
},
"from": {
"type": "string",
"description": "寄件人"
},
"to": {
"type": "string",
"description": "收件人"
},
"sender": {
"type": "string",
"description": "寄件人email"
},
"recipient": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"UUID": {
"type": "string"
}
}
}
}
},
"eventTime": {
"type": "string",
"description": "事件時間"
},
"rawEvent": {
"type": "object",
"properties": {}
}
}
}
}
}
}
Headers
Content-Type: application/json
Body
{
"error": "錯誤原因訊息"
}
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"logs": [
{
"messageId": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"status": "retry",
"mail": {
"subject": "系統通知信",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"sender": "bao@newsleopard.com",
"recipient": "bob@gmail.com",
"variables": {
"UUID": "1234-56-78-9012"
}
},
"eventTime": "2019-12-15T08:38:32Z",
"rawEvent": {}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "信件ID"
},
"status": {
"type": "string",
"description": "事件類型"
},
"mail": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"content": {
"type": "string",
"description": "信件內容"
},
"from": {
"type": "string",
"description": "寄件人"
},
"to": {
"type": "string",
"description": "收件人"
},
"sender": {
"type": "string",
"description": "寄件人email"
},
"recipient": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"UUID": {
"type": "string"
}
}
}
}
},
"eventTime": {
"type": "string",
"description": "事件時間"
},
"rawEvent": {
"type": "object",
"properties": {}
}
}
}
}
}
}
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"logs": [
{
"messageId": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"status": "delivery",
"mail": {
"subject": "系統通知信",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"sender": "bao@newsleopard.com",
"recipient": "bob@gmail.com",
"variables": {
"UUID": "1234-56-78-9012"
}
},
"eventTime": "2019-12-15T08:38:32Z",
"rawEvent": {}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "信件ID"
},
"status": {
"type": "string",
"description": "事件類型"
},
"mail": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"content": {
"type": "string",
"description": "信件內容"
},
"from": {
"type": "string",
"description": "寄件人"
},
"to": {
"type": "string",
"description": "收件人"
},
"sender": {
"type": "string",
"description": "寄件人email"
},
"recipient": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"UUID": {
"type": "string"
}
}
}
}
},
"eventTime": {
"type": "string",
"description": "事件時間"
},
"rawEvent": {
"type": "object",
"properties": {}
}
}
}
}
}
}
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"logs": [
{
"messageId": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"status": "open",
"mail": {
"subject": "系統通知信",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"sender": "bao@newsleopard.com",
"recipient": "bob@gmail.com",
"variables": {
"UUID": "1234-56-78-9012"
}
},
"eventTime": "2019-12-15T08:38:32Z",
"rawEvent": {
"clientHeaders": "User-Agent=Mozilla/5.0 Chrome/81.0.4044.129 Safari/537.36"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "信件ID"
},
"status": {
"type": "string",
"description": "事件類型"
},
"mail": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"content": {
"type": "string",
"description": "信件內容"
},
"from": {
"type": "string",
"description": "寄件人"
},
"to": {
"type": "string",
"description": "收件人"
},
"sender": {
"type": "string",
"description": "寄件人email"
},
"recipient": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"UUID": {
"type": "string"
}
}
}
}
},
"eventTime": {
"type": "string",
"description": "事件時間"
},
"rawEvent": {
"type": "object",
"properties": {
"clientHeaders": {
"type": "string",
"description": "用戶標頭"
}
}
}
}
}
}
}
}
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"logs": [
{
"messageId": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"status": "click",
"mail": {
"subject": "系統通知信",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"sender": "bao@newsleopard.com",
"recipient": "bob@gmail.com",
"variables": {
"UUID": "1234-56-78-9012"
}
},
"eventTime": "2019-12-15T08:38:32Z",
"rawEvent": {
"sort": "0",
"linkUrl": "https://newsleopard.com/",
"clientHeaders": "User-Agent=Mozilla/5.0 Chrome/81.0.4044.129 Safari/537.36"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "信件ID"
},
"status": {
"type": "string",
"description": "事件類型"
},
"mail": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"content": {
"type": "string",
"description": "信件內容"
},
"from": {
"type": "string",
"description": "寄件人"
},
"to": {
"type": "string",
"description": "收件人"
},
"sender": {
"type": "string",
"description": "寄件人email"
},
"recipient": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"UUID": {
"type": "string"
}
}
}
}
},
"eventTime": {
"type": "string",
"description": "事件時間"
},
"rawEvent": {
"type": "object",
"properties": {
"sort": {
"type": "string",
"description": "信內連結順序"
},
"linkUrl": {
"type": "string",
"description": "連結"
},
"clientHeaders": {
"type": "string",
"description": "用戶標頭"
}
}
}
}
}
}
}
}
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"logs": [
{
"messageId": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"status": "bounce",
"mail": {
"subject": "系統通知信",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"sender": "bao@newsleopard.com",
"recipient": "bob@gmail.com",
"variables": {
"UUID": "1234-56-78-9012"
}
},
"eventTime": "2019-12-15T08:38:32Z",
"rawEvent": {
"code": "451",
"type": "0",
"reason": "Internal resource temporarily unavailable - https://community.mimecast.com/docs/DOC-1369#451 [e2v-qRg9O1y4DLy5or9YqA.us411]"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "信件ID"
},
"status": {
"type": "string",
"description": "事件類型"
},
"mail": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"content": {
"type": "string",
"description": "信件內容"
},
"from": {
"type": "string",
"description": "寄件人"
},
"to": {
"type": "string",
"description": "收件人"
},
"sender": {
"type": "string",
"description": "寄件人email"
},
"recipient": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"UUID": {
"type": "string"
}
}
}
}
},
"eventTime": {
"type": "string",
"description": "事件時間"
},
"rawEvent": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "SMTP code"
},
"type": {
"type": "string",
"description": "退信類型"
},
"reason": {
"type": "string",
"description": "退信原因"
}
}
}
}
}
}
}
}
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"logs": [
{
"messageId": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
"status": "complaint",
"mail": {
"subject": "系統通知信",
"content": "<html><body><h3>Hello, World</h3></body></html>",
"from": "豹小編 <bao@newsleopard.com>",
"to": "bob <bob@gmail.com>",
"sender": "bao@newsleopard.com",
"recipient": "bob@gmail.com",
"variables": {
"UUID": "1234-56-78-9012"
}
},
"eventTime": "2019-12-15T08:38:32Z",
"rawEvent": {}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"logs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"messageId": {
"type": "string",
"description": "信件ID"
},
"status": {
"type": "string",
"description": "事件類型"
},
"mail": {
"type": "object",
"properties": {
"subject": {
"type": "string",
"description": "信件主旨"
},
"content": {
"type": "string",
"description": "信件內容"
},
"from": {
"type": "string",
"description": "寄件人"
},
"to": {
"type": "string",
"description": "收件人"
},
"sender": {
"type": "string",
"description": "寄件人email"
},
"recipient": {
"type": "string",
"description": "收件人email"
},
"variables": {
"type": "object",
"properties": {
"UUID": {
"type": "string"
}
}
}
}
},
"eventTime": {
"type": "string",
"description": "事件時間"
},
"rawEvent": {
"type": "object",
"properties": {}
}
}
}
}
}
}
事件查詢GET/v1/events{?from,to,status,id,recipient}
用途說明
本服務提供針對特定收件人進行寄送紀錄查證,以確認該信件目前狀況,可查詢的事件包括:accept(已接收請求)、retry(寄信重試)、delivery(到達)、open(開信)、click(點擊)、bounce(退信)、complaint(抱怨)。
URI Parameters
Parameters | 型別 | 說明 |
---|---|---|
id * |
string |
信件ID (與 recipient 擇一) |
recipient * |
string |
收件人address (與 id 擇一) |
from |
string |
查詢區間起始時間,格式範例:2019-12-15T08:38:32Z 請確認日期時間為 UTC+0 |
from 未帶入將自動給定預設值, 如果有帶入 to,from 的預設值為 to 的前一個月; 如果未帶入 to,則 from 的預設值為當天的前一個月 |
||
to |
string |
查詢區間結束時間,格式範例:2019-12-25T08:38:32Z ,請確認日期時間為 UTC+0 |
to 未帶入將自動給定預設值, 如果有帶入 from,to 的預設值為 from 的後一個月; 如果未帶入 from,則 to 的預設值為當天 |
||
status |
string |
事件類型,分別為: ・accept(已接收請求) ・retry(寄信重試) ・delivery(到達) ・open(開信) ・click(點擊) ・bounce(退信) ・complaint(抱怨) 可多選,需使用半形逗號 , 作分隔。 |
* 必填欄位
Response 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
messageId |
string |
信件ID |
status |
string |
事件類型,分別為: ・accept(已接收請求) ・retry(寄信重試) ・delivery(到達) ・open(開信) ・click(點擊) ・bounce(退信) ・complaint(抱怨) |
mail.subject |
string |
信件主旨 |
mail.content |
string |
信件內容 |
mail.from |
string |
寄件人 |
mail.to |
string |
收件人 |
mail.sender |
string |
寄件人Email |
mail.recipient |
string |
收件人Email |
mail.variables |
object |
收件人的變數 |
eventTime |
string |
事件時間 |
rawEvent.clientHeaders |
string |
收件人的表頭資訊 |
rawEvent.sort |
string |
連結順序,按照信件內容的連結順序排序,0 表示第一個,以此類推 |
rawEvent.linkUrl |
string |
點擊網址 |
rawEvent.code |
string |
SMTP code |
rawEvent.type |
string |
退信類型,0:暫時退信;1:永久退信 |
rawEvent.reason |
string |
退信原因 |
備註
-
只能查近 30 天內的資料,且若查出來的筆數超過 50 筆,僅會回傳前 50 筆資料,若需保留完整事件紀錄,請參考:數據追蹤服務章節,事先設定好 Webhook,將事件留存於自家系統中查詢
-
若URI Parameters 同時存在 id 及 recipient,將優先以 id 查詢事件
- id
string
(optional) Example: 20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7信件ID
- recipient
string
(optional) Example: user@gmail.com收件人信箱
- from
string
(optional) Example: 2019-12-15T08:38:32Z開始日期時間
格式:2019-12-15T08:38:32Z
備註: 請確認日期時間為UTC+0
- to
string
(optional) Example: 2019-12-25T08:38:32Z結束日期時間
格式:2019-12-25T08:38:32Z
備註: 請確認日期時間為UTC+0
- status
string
(optional) Example: accept,retry,open事件類型
accept (接收)
retry (重試)
delivery (到達)
open (開信)
click (點擊)
bounce (退信)
complaint (抱怨)
數位簽章設定服務 ¶
建立數位簽章 ¶
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
[
{
"name": "yours.domain.com",
"value": "v=spf1 include:amazonses.com include:mailgun.org ?all",
"record_type": 0,
"valid": "false"
}
]
建立數位簽章POST/v1/domains/{domain}
用途說明
可透過本服務取得數位簽章的設定檔,於 DNS Server 中進行設定。設定完成後,請參考: 驗證數位簽章 進行後續驗證。設定數位簽章,可以確保信件確實是由你所設定的網域發出,內容未被偽冒、竄改,以確保其正確性及可信度,將有效提高信件的寄送品質。
URI Parameters
Parameters | 型別 | 說明 |
---|---|---|
domain * |
string |
欲設定數位簽章之 sender domain |
* 必填欄位
Response 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
name |
string |
設定數位簽章的 sender domain |
value |
string |
設定檔 |
record_type |
number |
DNS 紀錄設定,0:TXT;1:CNAME |
valid |
boolean |
驗證通過與否,ture 或 false |
- domain
string
(required)欲驗證數位簽章之 domain
驗證數位簽章 ¶
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
[
{
"name": "yours.domain.com",
"value": "v=spf1 include:amazonses.com include:mailgun.org ?all",
"record_type": 0,
"valid": "true"
}
]
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}
驗證數位簽章PUT/v1/domains/{domain}
用途說明
可透過本服務進行數位簽章之驗證,確認 DNS Server 上的設定是否已生效。
URI Parameters
Parameters | 型別 | 說明 |
---|---|---|
domain * |
string |
欲設定數位簽章之 sender domain |
* 必填欄位
Response 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
name |
string |
設定數位簽章的 sender domain |
value |
string |
設定檔 |
record_type |
number |
DNS 紀錄設定,0:TXT;1:CNAME |
valid |
boolean |
驗證通過與否,ture 或 false |
- domain
string
(required)欲驗證數位簽章之 domain
刪除數位簽章 ¶
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Headers
Content-Type: application/json
Body
{
"success": true,
}
Headers
Content-Type: application/json
Body
{
"success": false,
}
刪除數位簽章DELETE/v1/domains/{domain}
用途說明
可透過本服務刪除已建立的數位簽章。
URI Parameters
Parameters | 型別 | 說明 |
---|---|---|
domain * |
string |
欲設定數位簽章之 sender domain |
* 必填欄位
Response 欄位說明
欄位 | 型別 | 說明 |
---|---|---|
success |
boolean |
刪除成功與否,ture 或 false |
- domain
string
(required)欲刪除數位簽章之 domain