歡迎使用電子豹
為了更好的體驗，請使用大於 1024*768px 的螢幕瀏覽
登入註冊

Surenotify API 文件

API Endpoint
https://mail.surenotifyapi.com

Overview

電子豹 Surenotify 推出的通知（Transactional）型 API，讓開發者可透過 API 操作的方式，完成 Email 或 SMS 等系統觸發通知用途，像是 Email 帳號啟用信、Email 忘記密碼信、Email 購物車未結帳提醒、SMS 到貨通知、SMS 手機驗證碼等，提供更即時的顧客服務體驗。 Surenotify 主要分成四個部分：

  • 寄信服務

  • 數據追蹤服務

  • 寄送狀態查證服務

  • Email 數位簽章設定 或 SMS 專屬門號設定

各項服務的 API 使用說明，請參閱章節內文，有任何問題皆歡迎來信詢問。

身份驗證

  1. 進行 API 連線時，必須在 request header 中帶入驗證資訊：

    key value
    x-api-key 金鑰內容

  2. 若沒有帶入驗證資訊，或是金鑰內容有誤，將會回傳：

    {"message": "Forbidden"}

  3. 如何申請 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

簡訊範例

以下為到貨通知的範例：

親愛的 {{nickname}} 您好，你的包裹已送達，請攜帶雙證件前往取貨。您的取貨編號為： {{number}}

假設透過下面的 request 範例分別寄給 Alice 及 Bob

{
    "content": "親愛的 {{NAME}} 您好，你的包裹已送達，請攜帶雙證件前往取貨。您的取貨編號為： {{NUMBER}}",
    "recipients": [
        {
            "address": "0912345678",
            "country_code": "886",
            "variables": {
                "nickname": "Alice",
                "number": "Xa98eG",
            }
        },
        {
            "address": "0987654321",
            "country_code": "886",
            "variables": {
                "nickname": "Bob",
                "number": "YY09dq",
            }
        }
    ]
}

Alice 收到的內容會是 親愛的 Alice 您好，你的包裹已送達，請攜帶雙證件前往取貨。您的取貨編號為： Xa98eG
Bob 收到的內容會是 親愛的 Bob 您好，你的包裹已送達，請攜帶雙證件前往取貨。您的取貨編號為： YY09dq

簡訊支援發送地區一覽表

洲別 國家代碼 英文國名 中文國名
亞洲 60 Malaysia 馬來西亞
亞洲 62 Indonesia 印尼
亞洲 63 Philippines 菲律賓
亞洲 65 Singapore 新加坡
亞洲 66 Thailand 泰國
亞洲 670 Timor Leste 東帝汶
亞洲 673 Brunei 汶萊
亞洲 7 Russia 俄羅斯
亞洲 77 Kazakhstan 哈薩克
亞洲 81 Japan 日本
亞洲 82 Korea 韓國
亞洲 84 Vietnam 越南
亞洲 852 Hong Kong 香港
亞洲 853 Macau 澳門
亞洲 855 Cambodia 柬埔寨
亞洲 856 Laos 寮國
亞洲 86 China 大陸
亞洲 880 Bangladesh 孟加拉
亞洲 90 Turkey 土耳其
亞洲 91 India 印度
亞洲 92 Pakistan 巴基斯坦
亞洲 93 Afghanistan 阿富汗
亞洲 94 Sri Lanka 斯里蘭卡
亞洲 95 Myanma 緬甸
亞洲 961 Lebanon 黎巴嫩
亞洲 962 Jordan 約旦
亞洲 963 Syria 敘利亞
亞洲 964 Iraq 伊拉克
亞洲 965 Kuwait 科威特
亞洲 966 Saudi Arabia 沙烏地阿拉伯
亞洲 967 Yemen 葉門
亞洲 968 Oman 阿曼
亞洲 970 Palestine 巴勒斯坦
亞洲 971 UAE 阿拉伯聯合大公國
亞洲 972 Israel 以色列
亞洲 973 Bahrain 巴林
亞洲 974 Qatar 卡達
亞洲 975 Bhutan 不丹
亞洲 976 Mongolia 蒙古
亞洲 977 Nepal 尼泊爾
亞洲 98 Iran 伊朗
亞洲 992 Tajikistan 坦吉克
亞洲 993 Turkmenistan 土庫曼
亞洲 996 Kyrgyzstan 吉爾吉斯坦
大洋洲 61 Australia 澳大利亞
大洋洲 64 New Zealand 紐西蘭
大洋洲 674 Nauru 諾魯
大洋洲 675 Papua New Guinea 巴布亞紐幾內亞
大洋洲 676 Tonga 東加王國
大洋洲 677 Solomon Islands 索羅門群島
大洋洲 678 Vanuatu 萬那度
大洋洲 679 Fiji 斐濟
大洋洲 680 Republic of Palau 帛琉
大洋洲 682 Cook Islands 庫克群島
大洋洲 685 Samoa 薩摩亞
大洋洲 686 Kiribati 吉里巴斯共和國
大洋洲 687 New Caledonia 法屬新喀里多尼亞
大洋洲 689 French Polynesia 法屬波里尼西亞
大洋洲 960 Maldives 馬爾地夫
歐洲 30 Greece 希臘
歐洲 31 Netherlands 荷蘭
歐洲 32 Belgium 比利時
歐洲 33 France 法國
歐洲 34 Spain 西班牙
歐洲 350 Gibraltar 直布羅陀
歐洲 351 Portugal 葡萄牙
歐洲 352 Luxembourg 盧森堡
歐洲 353 Ireland 愛爾蘭
歐洲 354 Iceland 冰島
歐洲 356 Malta 馬爾他
歐洲 357 Cyprus 賽普勒斯
歐洲 358 Finland 芬蘭
歐洲 359 Bulgaria 保加利亞
歐洲 36 Hungary 匈牙利
歐洲 370 Lithuania 立陶宛
歐洲 371 Latvia 拉脫維亞
歐洲 372 Estonia 愛沙尼亞
歐洲 373 Moldova 摩爾多瓦
歐洲 374 Armenia 亞美尼亞
歐洲 375 Belarus 白俄羅斯
歐洲 377 Kosovo 柯索沃/摩納哥
歐洲 380 Ukraine 烏克蘭
歐洲 381 Serbia 賽爾維亞
歐洲 382 Montenegro 蒙特內哥羅
歐洲 385 Croatia 克羅埃西亞共和國
歐洲 386 Slovenia 斯洛維尼亞
歐洲 387 Bosnia and Herzegovina 波士尼亞赫塞哥維納
歐洲 389 Macedonia 馬其頓共和國
歐洲 39 Italy 義大利
歐洲 40 Romania 羅馬尼亞
歐洲 41 Switzerland 瑞士
歐洲 420 Czech 捷克
歐洲 421 Slovakia 斯洛伐克
歐洲 423 Liechtenstein 列支敦斯登
歐洲 43 Austria 奧地利
歐洲 44 UK 英國
歐洲 45 Denmark 丹麥
歐洲 46 Sweden 瑞典
歐洲 47 Norway 挪威
歐洲 48 Poland 波蘭
歐洲 49 Germany 德國
歐洲 599 Netherlands Antilles 荷屬安地列斯
歐洲 882 Norway Maritime 挪威船舶
歐洲 994 Azerbaijan 亞賽拜然
歐洲 995 Georgia 喬治亞
歐洲 998 Uzbekistan 烏茲別克斯坦
美洲 1 USA 美國
美洲 11 Canada 加拿大
美洲 1242 Bahamas 巴哈馬
美洲 124625 Barbados 巴貝多
美洲 126447 Anguilla 英屬安圭拉島
美洲 126876 Antigua & Barbud 安地卡及巴布達
美洲 128454 British Virgin Islands 英屬處女島
美洲 134599 Cayman Islands 英屬開曼群島
美洲 147340 Gernada 格瑞那達
美洲 16492 Turks & Caicos 英屬土克思&開柯斯群
美洲 166449 Montserrat 蒙哲臘
美洲 175828 St. Lucia 聖露西亞
美洲 176727 Dominica 多米尼克
美洲 178449 St. Vincent 聖文森島國
美洲 1809 Dominicana 多明尼加共和國
美洲 186966 St. Kitts/Nevis 聖克里斯多福及尼維
美洲 187682 Jamaica 牙買加
美洲 1939 Puerto Rico 波多黎各
美洲 297 Aruba 阿廬巴島
美洲 501 Belize 貝里斯
美洲 502 GUATEMALA 瓜地馬拉
美洲 503 El_Salvador 薩爾瓦多
美洲 504 Honduras 宏都拉斯
美洲 505 Nicaragua 尼加拉瓜
美洲 506 Costa Rica 哥斯大黎加
美洲 509 HAITI 海地
美洲 51 Peru 秘魯
美洲 52 Mexico 墨西哥
美洲 53 Cuba 古巴
美洲 54 Argentina 阿根廷
美洲 55 Brazil 巴西
美洲 56 Chile 智利
美洲 57 Colombia 哥倫比亞
美洲 590 Carribean 瓜德羅普
美洲 591 Bolivia 玻利維亞
美洲 592 Guyana 圭亞那
美洲 593 Ecuado 厄瓜多爾
美洲 595 Paraguay 巴拉圭
美洲 597 Suriname 蘇利南
美洲 598 Uruguay 烏拉圭
美洲 71401 Panama 巴拿馬
非洲 20 Egypt 埃及
非洲 211 South Sudan 南蘇丹
非洲 212 Morocco 摩洛哥
非洲 213 Algeria 阿爾及利亞
非洲 216 Turusia 突尼西亞
非洲 220 Gambia 甘比亞
非洲 221 Senegal 塞內加爾
非洲 222 Mauritania 茅利塔尼亞
非洲 223 Mali 馬利
非洲 224 Guinea 幾內亞
非洲 225 Ivory Coast 象牙海岸
非洲 226 Burkina Faso 布吉納法索
非洲 227 Niger 尼日
非洲 228 Togo 多哥
非洲 229 Benin 貝南
非洲 230 Mauritius 模里西斯
非洲 231 Liberia 賴比瑞亞
非洲 233 Ghana 迦納
非洲 234 Nigeria 奈及利亞
非洲 235 Chad 查德
非洲 236 Central African Rep 中非共和國
非洲 237 Cameroun 喀麥隆
非洲 238 Cape Verde 維德角
非洲 239 São Tomé and Príncipe 聖多美普林西比
非洲 241 Gabon 加彭
非洲 242 Congo 剛果
非洲 243 The Democratic Republic of the Congo 剛果民主共和國
非洲 245 Bissau 幾內亞比紹
非洲 248 Seychelles 塞席爾
非洲 249 Sudan 蘇丹
非洲 250 Rwanda 盧安達
非洲 254 Kenya 肯亞
非洲 255 Tanzania 坦尚尼亞
非洲 256 Uganda 烏干達
非洲 257 Burundi 蒲隆地
非洲 258 Mozambique 莫三比克
非洲 260 Zambia 尚比亞
非洲 261 Madagascar 馬達加斯加
非洲 262 Reunion 留尼旺
非洲 263 Zimbabwe 辛巴威
非洲 264 Namibia 那米比亞
非洲 265 Malawi 馬拉威
非洲 266 Lesotho 賴索托
非洲 268 Swaziland 史瓦濟蘭
非洲 27 South Africa 南非
非洲 355 Albania 阿爾巴尼亞
非洲 652 Botswana 波扎那

Webhook 使用說明

用途說明
提供行為事件追蹤服務，並透過 Webhook 的方式，即時將相關事件回傳。

回傳方式
以 HTTP POST 方式傳送至使用者設定的 URL

Signature 驗證
為了確保 request 是由 電子豹 Surenotify 所發出，使用者可以驗證 request header 內的 x-surenotify-signature 來確認是否由本服務所發出

  • 驗證步驟：
    1. 取得 Surenotify 回傳 header 內的 x-surenotify-signature
    2. 取得 body 內 id 與 event (id , eventType)
    3. 將 id 與 eventType 組成字串
    4. 將 API key (x-api-key) 設為 secret key 以 HmacSHA256 將 message 加密產生 Hex 字串 (signature)
    5. 比對 header 內的 x-surenotify-signature 與 計算出的 signature 是否相等

範例：
id = 20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7
eventType = delivery 組合後字串 = 20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7delivery

Email Webhook 欄位說明/範例

欄位說明

欄位 型別 說明
event string 事件類型，分別為：
・delivery（到達）
・open（開信）
・click（點擊）
・bounce（退信）
・complaint（抱怨）
id string 信件 ID
subject string 信件主旨
content string 信件內容
from string 寄件人
to string 收件人
variables object 收件人的變數
delivery.timestamp long 到達時間
open.timestamp long 開信時間
open.client_headers string 收件人的表頭資訊
click.timestamp long 點擊時間
click.sort string 連結順序，按照信件內容的連結順序排序，0 表示第一個，以此類推
click.link_url string 點擊網址
click.client_headers string 收件人的表頭資訊
bounce.timestamp long 退信時間
bounce.code string SMTP code
bounce.type number 退信類型，0：暫時退信；1：永久退信
bounce.reason string 退信原因
complaint.timestamp long 抱怨時間

範例：
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 事件的情況，請注意。

Sms Webhook 欄位說明/範例

欄位說明

欄位 型別 說明
event string 事件類型，分別為：
・delivery（到達）
・bounce（退信）
id string 信件 ID
content string 信件內容
variables object 收件人的變數
alive_mins number 嘗試 Retry 的期限，單位為「分鐘」，設定值範圍：5 ~ 480，參數無給定，預設為最小值，參數值低於最小值或高於最大值，則視為最小值或最大值。alive_mins 設定時間越長，有利簡訊到達成效最大化，但需等待 alive_mins 時間結束才能收到最終 webhook 結果，建議依不同情境的即時性需求斟酌設定
recipient string 收件人
address string 收件人電話
country_code string 收件人國碼
delivery.timestamp long 到達時間
delivery.point number 計價封數
delivery.srcaddr string 寄件人電話
bounce.timestamp long . 退信時間
bounce.code string 錯誤代碼
bounce.reason string 錯誤原因

範例：
delivery（到達）

{
    "event": "delivery",
    "sms_data": {
        "id": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
        "content": "豹小編誠心邀請你加入電子豹的大家庭",
        "recipient": "886912345678",
        "address": "0912345678",
        "country_code": "886",
        "variables": {
            "UUID": "1234-56-78-9012"
        },
        "alive_mins": 5
    },
    "delivery": {
        "timestamp": 1577836800000,
        "point": 1,
        "srcaddr": "0988777666",
    }
}

bounce（退信）

{
    "event": "bounce",
    "sms_data": {
        "id": "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7",
        "content": "豹小編誠心邀請你加入電子豹的大家庭",
        "recipient": "886912345678",
        "address": "0912345678",
        "country_code": "886",
        "variables": {
            "UUID": "1234-56-78-9012"
        },
        "alive_mins": 5
    },
    "bounce": {
        "timestamp": 1577836800000,
        "code": "-5",
        "reason": "destination number invalid",
    }
}

郵件 API

單筆/多筆寄送

POST https://mail.surenotifyapi.com/v1/messages
Requests單筆寄送多筆批次寄送
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
HideShow
{
  "$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"
  ]
}
Responses200
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
HideShow
{
  "$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
HideShow
{
  "$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"
  ]
}
Responses200400
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",
    "variable_too_long@gmail.com": "Invalid: the value of recipient variables should under 100 characters"
  }
}
Schema
HideShow
{
  "$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"
            },
            "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 的名稱。
例如：support@newsleopard.com 中的 support 作為寄件人姓名
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

POST https://mail.surenotifyapi.com/v1/webhooks
Requests新增/修改 webhook
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
  "type": 3,
  "url": "https://urwebhook.com"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "number",
      "description": "事件類型"
    },
    "url": {
      "type": "string",
      "description": "webhook位址"
    }
  },
  "required": [
    "type"
  ]
}
Responses200400
Headers
Content-Type: application/json
Body
{
  "success": true
}
Headers
Content-Type: application/json
Body
{
  "success": false,
  "messages": [
    "Invalid: type is not a valid value."
  ]
}

新增/修改 Webhook
POST/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

GET https://mail.surenotifyapi.com/v1/webhooks
Requests查詢 webhook
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200
Headers
Content-Type: application/json
Body
{
  "type": 3,
  "domain": "default",
  "url": "https://urwebhook.com",
  "createDate": "2019-03-05T08:19:26Z"
}
Schema
HideShow
{
  "$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"
  ]
}

查詢 Webhook
GET/v1/webhooks

用途說明

本服務讓你可查詢目前已設定的所有 Webhook 內容。

Response 欄位說明

欄位 型別 說明
type number 事件類型代碼，分別為：
・delivery（到達）：3
・open（開信）：4
・click（點擊）：5
・bounce（退信）：6
・complaint（抱怨）：7
domain string 網域名稱
url string Webhook 註冊網址
createDate string 建立時間

刪除 Webhook

DELETE https://mail.surenotifyapi.com/v1/webhooks
Requests刪除 webhook
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
  "type": 3
}
Responses200500
Headers
Content-Type: application/json
Body
{
    "success": true,
}
Headers
Content-Type: application/json
Body
{
    "success": false,
}

刪除 Webhook
DELETE/v1/webhooks

用途說明

本服務讓你可刪除目前已設定的 Webhook 內容。

Request 欄位說明 * 必填欄位

欄位 型別 說明
type * number 事件類型代碼，分別為：
・delivery（到達）：3
・open（開信）：4
・click（點擊）：5
・bounce（退信）：6
・complaint（抱怨）：7

Response 欄位說明

欄位 型別 說明
success boolean 刪除成功與否，ture 或 false

事件查詢

GET https://mail.surenotifyapi.com/v1/events?from=2019-12-15T08:38:32Z&to=2019-12-25T08:38:32Z&status=accept,retry,open&id=20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7&recipient=user@gmail.com
RequestsAcceptRetryDeliveryOpenClickBounceComplaint
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200400
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
HideShow
{
  "$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
Responses200
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
HideShow
{
  "$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
Responses200
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
HideShow
{
  "$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
Responses200
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
HideShow
{
  "$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
Responses200
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
HideShow
{
  "$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
Responses200
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
HideShow
{
  "$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
Responses200
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
HideShow
{
  "$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章節，事先設定好 Webhook，將事件留存於自家系統中查詢

  • 若URI Parameters 同時存在 id 及 recipient，將優先以 id 查詢事件

URI Parameters
HideShow
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 (抱怨)

建立數位簽章

POST https://mail.surenotifyapi.com/v1/domains/domain
Requests建立數位簽章
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200
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
URI Parameters
HideShow
domain
string (required) 

欲驗證數位簽章之 domain

驗證數位簽章

PUT https://mail.surenotifyapi.com/v1/domains/domain
Requests驗證數位簽章
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200
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
HideShow
{
  "$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
URI Parameters
HideShow
domain
string (required) 

欲驗證數位簽章之 domain

刪除數位簽章

DELETE https://mail.surenotifyapi.com/v1/domains/domain
Requests刪除數位簽章
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200500
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
URI Parameters
HideShow
domain
string (required) 

欲刪除數位簽章之 domain

簡訊 API

單筆/多筆寄送

POST https://mail.surenotifyapi.com/v1/sms/messages
Requests單筆寄送多筆批次寄送
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
  "from": "0987654321",
  "content": "這是簡訊測試內容，收到請勿回覆",
  "alive_mins": 5,
  "recipients": [
    {
      "address": "0912345678",
      "country_code": "886",
      "variables": {
        "UUID": "1234-56-78-9012"
      }
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "寄件人電話"
    },
    "content": {
      "type": "string",
      "description": "簡訊內容"
    },
    "alive_mins": {
      "type": "number",
      "description": "Retry時間"
    },
    "recipients": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "收件人電話"
          },
          "country_code": {
            "type": "string",
            "description": "收件人國碼｀"
          },
          "variables": {
            "type": "object",
            "properties": {
              "UUID": {
                "type": "string"
              }
            }
          }
        },
        "required": [
          "address",
          "country_code"
        ]
      }
    }
  },
  "required": [
    "content"
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "7897e18f-19bc-44eb-9149-e95e9ffc5d27",
  "success": [
    {
      "id": "20191107080336-47f09d97-9a46-4215-bdb7-de68eca1c436",
      "address": "0912345678"
    }
  ],
  "failure": {}
}
Schema
HideShow
{
  "$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
{
  "from": "0987654321",
  "content": "這是簡訊測試內容，收到請勿回覆",
  "alive_mins": 5,
  "recipients": [
    {
      "address": "0912345678",
      "country_code": "886",
      "variables": {
        "gender": "woman"
      }
    },
    {
      "address": "=0933444888",
      "country_code": "886",
      "variables": {
        "gender": "man"
      }
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "寄件人電話"
    },
    "content": {
      "type": "string",
      "description": "簡訊內容"
    },
    "alive_mins": {
      "type": "number",
      "description": "Retry時間"
    },
    "recipients": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "address": {
              "type": "string",
              "description": "收件人電話"
            },
            "country_code": {
              "type": "string",
              "description": "收件人國碼｀"
            },
            "variables": {
              "type": "object",
              "properties": {
                "gender": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "address",
            "country_code"
          ]
        },
        {
          "type": "object",
          "properties": {
            "address": {
              "type": "string",
              "description": "收件人電話"
            },
            "country_code": {
              "type": "string",
              "description": "收件人國碼｀"
            },
            "variables": {
              "type": "object",
              "properties": {
                "gender": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "address",
            "country_code"
          ]
        }
      ]
    }
  },
  "required": [
    "content"
  ]
}
Responses200400
Headers
Content-Type: application/json
Body
{
  "id": "7897e18f-19bc-44eb-9149-e95e9ffc5d27",
  "success": {
    "id": "20191107080336-4ca1d97-216e-4a2b-b7ad-68deeac1c1ca6",
    "address": "0912345678"
  },
  "failure": {
    "=0933444888": "address is not a valid format"
  }
}
Schema
HideShow
{
  "$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": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "address": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "address"
          ],
          "additionalProperties": false
        }
      }
    },
    "failure": {
      "type": "object",
      "patternProperties": {
        "": {
          "type": "object",
          "properties": {
            "=0933444888": {
              "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/sms/messages

用途說明

透過本服務進行 簡訊 單筆或多筆之寄送，並可透過變數的使用 (請參考： 變數使用說明)，以達到個人化簡訊之效果。

Request 欄位說明 * 必填欄位

欄位 型別 說明
content * string 簡訊內容
recipients * array 收件人，最多放置 100 recipient / request
recipients.address * string 收件人電話，支援格式為純數字。範例：0912345678 或 912345678
recipients.country_code * string 收件人國碼，國碼清單請參考： 簡訊支援發送地區一覽表
recipients.variables object 收件人的變數，自定義，每個 variables 內容長度最長 100。
使用方式請參考：變數使用說明
from string 寄件人專屬門號，若無專屬門號則不用填
alive_mins number 嘗試 Retry 的期限，單位為「分鐘」，設定值範圍：5 ~ 480，參數無給定，預設為最小值，參數值低於最小值或高於最大值，則視為最小值或最大值。alive_mins 設定時間越長，有利簡訊到達成效最大化，但需等待 alive_mins 時間結束才能收到最終 webhook 結果，建議依不同情境的即時性需求斟酌設定

Response 欄位說明

欄位 型別 說明
id string request ID
success.id string 簡訊 ID
success.address string 收件人電話
failure object 收件人錯誤，類型如下：
・電話 格式不符：address is not a valid format
・內容為空：content can not be empty
・內容字數超過限制：content length 390 exceeds the limit 335

新增/修改 Webhook

POST https://mail.surenotifyapi.com/v1/sms/webhooks
Requests新增/修改 webhook
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
  "type": 3,
  "url": "https://urwebhook.com"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "number",
      "description": "事件類型"
    },
    "url": {
      "type": "string",
      "description": "webhook位址"
    }
  },
  "required": [
    "type"
  ]
}
Responses200400
Headers
Content-Type: application/json
Body
{
  "success": true
}
Headers
Content-Type: application/json
Body
{
  "success": false,
  "messages": [
    "Invalid: type is not a valid value."
  ]
}

新增/修改 Webhook
POST/v1/sms/webhooks

用途說明

本服務讓你可自行設定欲即時接收的事件 Webhook URL，以確認每封簡訊的寄送狀態，包括：delivery（到達）、bounce（退信）。

Request 欄位說明 * 必填欄位

欄位 型別 說明
type * number 事件類型代碼，分別為：
・delivery（到達）：3
・bounce（退信）：6
url * string Webhook 註冊網址

Response 欄位說明

欄位 型別 說明
success boolean 新增成功與否，ture 或 false
message array 新增失敗原因

備註

當新增的 type url紀錄不存在時，會新增資料；反之，則會修改原有紀錄

查詢 Webhook

GET https://mail.surenotifyapi.com/v1/sms/webhooks
Requests查詢 webhook
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200
Headers
Content-Type: application/json
Body
{
  "type": 3,
  "domain": "default",
  "url": "https://urwebhook.com",
  "createDate": "2019-03-05T08:19:26Z"
}
Schema
HideShow
{
  "$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"
  ]
}

查詢 Webhook
GET/v1/sms/webhooks

用途說明

本服務讓你可查詢目前已設定的所有 Webhook 內容。

Response 欄位說明

欄位 型別 說明
type number 事件類型代碼，分別為：
・delivery（到達）：3
・bounce（退信）：6
url string Webhook 註冊網址
createDate string 建立時間

刪除 Webhook

DELETE https://mail.surenotifyapi.com/v1/sms/webhooks
Requests刪除 webhook
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Body
{
  "type": 3
}
Responses200500
Headers
Content-Type: application/json
Body
{
    "success": true,
}
Headers
Content-Type: application/json
Body
{
    "success": false,
}

刪除 Webhook
DELETE/v1/sms/webhooks

用途說明

本服務讓你可刪除目前已設定的 Webhook 內容。

Request 欄位說明 * 必填欄位

欄位 型別 說明
type * number 事件類型代碼，分別為：
・delivery（到達）：3
・bounce（退信）：6

Response 欄位說明

欄位 型別 說明
success boolean 刪除成功與否，ture 或 false

事件查詢

GET https://mail.surenotifyapi.com/v1/sms/events?from=2019-12-15T08:38:32Z&to=2019-12-25T08:38:32Z&status=accept,delivery&id=20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7&recipient=0912345678&country_code=886
RequestsAcceptDeliveryBounce
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200400
Headers
Content-Type: application/json
Body
{
  "logs": [
    {
      "messageId": "20210401092034-0-bf4269e8-d30c-43bd-aa0a-668502050694",
      "recipient": "886912345678",
      "address": "0912345678",
      "countryCode": "886",
      "status": "accept",
      "content": "歡迎您註冊電子豹平台服務",
      "eventTime": "2021-04-01T09:20:34Z",
      "alive_mins": 5,
      "variables": {},
      "rawEvent": {}
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "logs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "messageId": {
            "type": "string",
            "description": "簡訊ID"
          },
          "recipient": {
            "type": "string",
            "description": "收件人"
          },
          "address": {
            "type": "string",
            "description": "收件人電話"
          },
          "countryCode": {
            "type": "string",
            "description": "收件人國碼"
          },
          "status": {
            "type": "string",
            "description": "事件類型"
          },
          "content": {
            "type": "string",
            "description": "簡訊內容"
          },
          "eventTime": {
            "type": "string",
            "description": "事件時間"
          },
          "alive_mins": {
            "type": "number",
            "description": "Retry時間"
          },
          "variables": {
            "type": "object",
            "properties": {}
          },
          "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
Responses200
Headers
Content-Type: application/json
Body
{
  "logs": [
    {
      "messageId": "20210401092034-0-bf4269e8-d30c-43bd-aa0a-668502050694",
      "recipient": "886912345678",
      "address": "0912345678",
      "countryCode": "886",
      "status": "delivery",
      "content": "歡迎您註冊電子豹平台服務",
      "eventTime": "2021-04-01T09:20:34Z",
      "alive_mins": 5,
      "variables": {},
      "rawEvent": {
        "point": "1",
        "srcaddr": "0988777666"
      }
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "logs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "messageId": {
            "type": "string",
            "description": "簡訊ID"
          },
          "recipient": {
            "type": "string",
            "description": "收件人"
          },
          "address": {
            "type": "string",
            "description": "收件人電話"
          },
          "countryCode": {
            "type": "string",
            "description": "收件人國碼"
          },
          "status": {
            "type": "string",
            "description": "事件類型"
          },
          "content": {
            "type": "string",
            "description": "簡訊內容"
          },
          "eventTime": {
            "type": "string",
            "description": "事件時間"
          },
          "alive_mins": {
            "type": "number",
            "description": "Retry時間"
          },
          "variables": {
            "type": "object",
            "properties": {}
          },
          "rawEvent": {
            "type": "object",
            "properties": {
              "point": {
                "type": "string",
                "description": "計價封數"
              },
              "srcaddr": {
                "type": "string",
                "description": "寄件人電話"
              }
            }
          }
        }
      }
    }
  }
}
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200
Headers
Content-Type: application/json
Body
{
  "logs": [
    {
      "messageId": "20210401092034-0-bf4269e8-d30c-43bd-aa0a-668502050694",
      "recipient": "886912345678",
      "address": "0912345678",
      "countryCode": "886",
      "status": "bounce",
      "content": "歡迎您註冊電子豹平台服務",
      "eventTime": "2021-04-01T09:20:34Z",
      "alive_mins": 5,
      "variables": {},
      "rawEvent": {
        "code": "-5",
        "reason": "destination number invalid"
      }
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "logs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "messageId": {
            "type": "string",
            "description": "簡訊ID"
          },
          "recipient": {
            "type": "string",
            "description": "收件人"
          },
          "address": {
            "type": "string",
            "description": "收件人電話"
          },
          "countryCode": {
            "type": "string",
            "description": "收件人國碼"
          },
          "status": {
            "type": "string",
            "description": "事件類型"
          },
          "content": {
            "type": "string",
            "description": "簡訊內容"
          },
          "eventTime": {
            "type": "string",
            "description": "事件時間"
          },
          "alive_mins": {
            "type": "number",
            "description": "Retry時間"
          },
          "variables": {
            "type": "object",
            "properties": {}
          },
          "rawEvent": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Error code"
              },
              "reason": {
                "type": "string",
                "description": "退信原因"
              }
            }
          }
        }
      }
    }
  }
}

事件查詢
GET/v1/sms/events{?from,to,status,id,recipient,country_code}

用途說明

本服務提供針對特定收件人進行寄送紀錄查證，以確認該信件目前狀況，可查詢的事件包括：accept（已接收請求）、delivery（到達）、bounce（退信）。

URI Parameters * 必填欄位

Parameters 型別 說明
id * string 簡訊ID (與 recipient 擇一)
recipient * string 收件人電話 (與 id 擇一)。範例：0912345678 或 912345678
country_code * string 收件人國碼 (與 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（已接收請求）
・delivery（到達）
・bounce（退信）

可多選，需使用半形逗號 , 作分隔。

Response 欄位說明

欄位 型別 說明
messageId string 簡訊ID
recipient string 收件人
address string 收件人電話
countryCode string 收件人國碼
status string 事件類型，分別為：
・accept（已接收請求）
・delivery（到達）
・bounce（退信）
content string 簡訊內容
eventTime string 事件時間
alive_mins number 嘗試 Retry 的期限，單位為「分鐘」，設定值範圍：5 ~ 480，參數無給定，預設為最小值，參數值低於最小值或高於最大值，則視為最小值或最大值。alive_mins 設定時間越長，有利簡訊到達成效最大化，但需等待 alive_mins 時間結束才能收到最終 webhook 結果，建議依不同情境的即時性需求斟酌設定
variables object 收件人的變數
rawEvent.point string 計價封數
rawEvent.srcaddr string 寄件人電話
rawEvent.code string 退信代碼
rawEvent.reason string 退信原因

備註

  • 只能查近 30 天內的資料，且若查出來的筆數超過 50 筆，僅會回傳前 50 筆資料，若需保留完整事件紀錄，請參考：新增/修改 webhook章節，事先設定好 Webhook，將事件留存於自家系統中查詢

  • 若URI Parameters 同時存在 id 及 recipient，將優先以 id 查詢事件

URI Parameters
HideShow
id
string (optional) Example: 20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7

簡訊ID

recipient
string (optional) Example: 0912345678

收件人電話

country_code
string (optional) Example: 886

收件人國碼

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,delivery

事件類型

accept (接收)
retry (重試)
delivery (到達)
open (開信)
click (點擊)
bounce (退信)
complaint (抱怨)

專屬門號查詢

GET https://mail.surenotifyapi.com/v1/sms/exclusive-number
Requests查詢專屬門號
Headers
Content-Type: application/json
Accept: application/json
x-api-key: Your API Key
Responses200
Headers
Content-Type: application/json
Body
{
    "phoneNumbers": [
        {
            "phoneNumber": "0988777666",
            "createDate": "2019-03-05T08:19:26Z`",
            "updateDate": "2019-03-05T09:31:26Z`",
        },
        {
            "phoneNumber": "0911222333",
            "createDate": "2019-04-05T08:19:26Z`",
            "updateDate": "2019-04-05T09:31:26Z`",
        }
    ]
}

專屬門號查詢
GET/v1/sms/exclusive-number

用途說明

本服務提供給已設有專屬門號之用戶進行門號查詢使用。使用專屬門號寄簡訊，可增進會員對於品牌的辨識度，以降低被詐騙之機會。有關專屬門號之申請，歡迎來信詢問。

Response 欄位說明

欄位 型別 說明
phoneNumber string 專屬門號
createDate string 建立時間
updateDate string 更新時間
快豹科技有限公司 版權所有 © 2021  隱私權政策  使用條款