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

Surenotify API 文件

API Endpoint
https://mail.surenotifyapi.com

Overview

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

  • 寄信服務

  • 數據追蹤服務

  • 寄送狀態查證服務

  • 數位簽章設定服務

各項服務的 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

單筆/多筆寄信

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": "too_many_variables",
      "address": "too_many_variables@gmail.com",
      "variables": {
        "v1": "variable1",
        "v2": "variable2",
        "v3": "variable3",
        "v4": "variable4",
        "v5": "variable5",
        "v6": "variable6",
        "v7": "variable7",
        "v8": "variable8",
        "v9": "variable9",
        "v10": "variable10",
        "v11": "variable11"
      }
    },
    {
      "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": {
                "v1": {
                  "type": "string"
                },
                "v2": {
                  "type": "string"
                },
                "v3": {
                  "type": "string"
                },
                "v4": {
                  "type": "string"
                },
                "v5": {
                  "type": "string"
                },
                "v6": {
                  "type": "string"
                },
                "v7": {
                  "type": "string"
                },
                "v8": {
                  "type": "string"
                },
                "v9": {
                  "type": "string"
                },
                "v10": {
                  "type": "string"
                },
                "v11": {
                  "type": "string"
                }
              }
            }
          },
          "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",
    "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
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"
            },
            "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 收件人的變數，自定義，最多放置 10 variables / recipient，每個 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 amount of recipient variables should under 10
・收件人變數內容過長：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",
    }
}
    1. 取得 Surenotify 回傳 header 內的 x-surenotify-signature
    2. 取得 body 內 mail id 與 event (mailId , eventType)
    3. 將 mailId 與 eventType 組成字串
      • 例: message = "20191217065433-0-08d0c68d-bd83-422b-9457-8cc7f0804ab7delivery"
    4. 將 API key (x-api-key) 設為 secret key 以 HmacSHA256 將 message 加密產生 Hex 字串 (signature)
    5. 比對 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

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，將事件留存於自家系統中查詢

  • 若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

快豹科技有限公司 版權所有 © 2020  隱私權政策  使用條款