CountdownMail API
本指南将帮助您开始使用 CountdownMail API。它涵盖了如何设置、验证身份、处理错误以及使用倒计时器。
快速入门
本节将帮助您准备好使用 CountdownMail API，并向您展示如何发出第一个 API 请求。
- 获取您的 API 密钥：
- 登录您的 CountdownMail 账户。
- 转到 个人资料 » API。
- 复制您的 API 密钥。
- 发出您的第一个 API 请求：
- 我们将以"创建计时器"端点为例。
- 使用 cURL 或 Postman 等工具向 https://countdownmail.com/api/create 发送 POST 请求。
- 在 Authorization 头中添加您的 API 密钥。
- 在请求正文中包含所需的计时器详细信息（JSON 格式）。
以下是使用 cURL 的示例：
请求
POST
https://countdownmail.com/api/create
curl -H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-X POST "https://countdownmail.com/api/create" \
-d '{
"skin_id": 1,
"name": "Big Sale!",
"time_end": "2025-04-21 20:00:00",
"time_zone": "America/Los_Angeles",
"font_family": "Roboto-Bold",
"color_primary": "FF3A43",
"color_text": "FFFFFF",
"color_bg": "000000"
}'
- 将 YOUR_API_KEY 替换为您的实际 API 密钥。
- 如果一切正常，您将收到类似这样的响应：
响应
{
"status": "success",
"message": {
"id": 1057,
"code": "td",
"src": "http://i.countdownmail.com/td.gif"
}
}
此响应包括计时器代码（例如"td"）和计时器图像的 URL。
身份验证
要使用 CountdownMail API，您需要使用 API 密钥验证每个请求。方法如下：
- 向请求添加 Authorization 头。值是您的 API 密钥。
- 或者，使用基本身份验证：将 API 密钥设置为用户名，密码留空。
Authorization 头示例 (cURL)：
请求
GET
https://countdownmail.com/api/some_endpoint
curl -H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-X GET "https://countdownmail.com/api/some_endpoint"
- 将 YOUR_API_KEY 替换为您的实际 API 密钥。
- 始终包含身份验证，否则您将收到 401 Unauthorized 错误。
使用 Postman
如果您使用 Postman，它可以轻松测试 API 请求。要与 CountdownMail 一起使用：
- 点击导入 CountdownMail API 集合。
- 将您的 API 密钥添加到集合的身份验证设置中，即可开始发送请求。
错误
有时 API 请求会失败。CountdownMail API 使用 HTTP 状态码告诉您出了什么问题。以下是可能的错误列表、含义及解决方法：
| 代码 | 状态名称 | 描述 | 建议操作 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 400 | 错误请求 | 您的请求有问题。 | 检查您的请求是否与文档匹配并使用正确的语法。 | ||||||||
| 401 | 未授权 | 您没有权限发出此请求。 | 确保您在 Authorization 头中使用有效的 API 密钥。 | ||||||||
| 404 | 未找到 | 服务器找不到您请求的内容。 | 验证您的 URL 是否与有效的 API 端点匹配。 | ||||||||
| 405 | 方法不允许 | 该端点不支持此方法。 | 使用文档中显示的正确 HTTP 方法（例如 GET、POST）。 | ||||||||
| 429 | 请求过多 | 客户端在 1 分钟内发送了太多请求。 | 您可以使用每个响应发送的头来确定当前速率限制的状态。
| ||||||||
| 500 | 内部服务器错误 | CountdownMail 端出现问题。 | 稍后重试。如果问题持续存在，请联系支持。 | ||||||||
| 503 | 服务不可用 | 服务器目前太忙。 | 稍等片刻后重试。 |
错误响应示例 (401 Unauthorized)：
响应
{
"status": "error",
"message": "Unauthorized"
}
如果看到错误，请检查状态码和消息，然后按照建议的操作进行。
计时器模型
计时器资源包含有关倒计时器的所有信息。以下是定义倒计时器可用的字段：
| 属性 | 类型 | 描述 | 必填 | 备注 |
|---|---|---|---|---|
| skin_id | 整数 | 计时器的设计样式（模板）。 | 是 | 必须是 1 到 23 之间的数字。 |
| name | 字符串 | 计时器名称。 | 是 | 最多 100 个字符。示例：Big Sale! |
| time_end | 字符串 | 计时器结束时间 (YYYY-MM-DD HH:MM:SS)。 | 是 | 示例：2025-04-09 04:57:16 |
| time_zone | 字符串 | 计时器的时区。 | 是 | 示例：America/Los_Angeles。查看所有可用的 time_zone 值。 |
| font_family | 字符串 | 计时器文本的字体。 | 否 | 示例：Roboto-Bold。查看所有可用的 font_family 值。 |
| label_font_family | 字符串 | 计时器标签的字体。 | 否 | 示例：Roboto-Bold。查看所有可用的 font_family 值。 |
| color_primary | 字符串 | 主颜色（十六进制代码）。 | 是 | 示例：FF3A43（红色）。 |
| color_text | 字符串 | 文本颜色（十六进制代码）。 | 是 | 示例：FFFFFF（白色）。 |
| color_bg | 字符串 | 背景颜色（十六进制代码）。 | 是 | 示例：000000（黑色）。 |
| font_size | 整数 | 计时器文本大小。 | 否 | 14 到 73 之间。 |
| label_font_size | 整数 | 标签文本大小。 | 否 | 0 到 50 之间。 |
| day | 整数 | 显示天数（0 = 否，1 = 是）。 | 否 | 必须是 0 或 1。 |
| lang | 字符串 | 语言代码（ISO 2 字母）。 | 否 | 示例：en（英语）。查看所有 54 种支持的语言。 |
| transparent | 整数 | 背景：0 = 纯色，1 = 透明。 | 否 | 必须是 0 或 1。 |
| expired_mes_on | 整数 | 显示到期消息（0 = 否，1 = 是）。 | 否 | 必须是 0 或 1。 |
| expired_mes | 字符串 | 计时器到期时的消息。 | 否 | 最多 100 个字符。示例：This offer has expired |
| labels | 整数 | 使用自定义标签（0 = 否，1 = 是）。 | 否 | 必须是 0 或 1。 |
| days | 字符串 | 天的标签。 | 否 | 最多 15 个字符。示例：days |
| hours | 字符串 | 小时的标签。 | 否 | 最多 15 个字符。示例：hours |
| minutes | 字符串 | 分钟的标签。 | 否 | 最多 15 个字符。示例：minutes |
| seconds | 字符串 | 秒的标签。 | 否 | 最多 15 个字符。示例：seconds |
| timer_type | 整数 | 计时器类型：1 = 共享日期计时器，2 = 个人计时器，3 = 链接计时器。 | 否 | 必须是1、2或3。默认为1（共享日期计时器）。 |
| duration | 整数 | 计时器持续时间（秒）（用于个人计时器）。 | 否 | 当timer_type为2（个人计时器）时必需。示例：86400（24小时）。 |
| advanced_params | 对象 | 额外设置（例如分隔符颜色）。 | 否 | 示例 |
创建计时器
此端点允许您创建计时器。要创建新计时器，您必须提供所有必填属性。
请求示例：
请求
POST
https://countdownmail.com/api/create
curl -H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-X POST "https://countdownmail.com/api/create" \
-d '{
"skin_id":3,
"name":"Big Sale!",
"time_end":"2026-02-02 20:00:00",
"time_zone":"America\/Los_Angeles",
"font_family":"Roboto-Bold",
"color_primary":"FF3A43",
"color_text":"FFFFFF",
"color_bg":"000000",
"transparent":"0",
"font_size":"38",
"lang":"en",
"expired_mes_on":"1",
"expired_mes":"This offer has expired",
"labels":"1",
"days":"days",
"hours":"hours",
"minutes":"minutes",
"seconds":"seconds"
}'
响应
{
"status": "success",
"message": {
"id": 1057,
"code": "td",
"src": "http://i.countdownmail.com/td.gif"
}
}
更新计时器
此端点允许您更新任何计时器属性。要更新计时器，请向 /update/{code} 发送包含要更新字段的 PUT 请求。将 {code} 替换为计时器代码（例如"td"）。
请求示例：
请求
PUT
https://countdownmail.com/api/update/{code}
curl -H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-X PUT "https://countdownmail.com/api/update/{code}" \
-d '{
"skin_id":6,
"name":"Flash Sale!",
"time_end":"2026-02-02 20:00:00"
}'
响应
{
"status": "success",
"message": {
"id": 1057,
"code": "td",
"src": "http://i.countdownmail.com/td.gif"
}
}
复制计时器
要复制现有计时器，请向 /duplicate/{code} 发送 POST 请求。将 {code} 替换为要复制的计时器的唯一代码。这将创建一个与原始计时器具有相同设置的新计时器。
您可以通过在请求正文中添加 JSON 对象来更新新计时器的详细信息。这样您可以更改特定属性（如结束时间或名称），同时保持其他设置与原始计时器相同。可以更新的属性与创建新计时器时可以设置的属性相同（完整列表请参阅计时器模型部分）。如果不包含某个属性，它将保持与原始计时器相同。
重要：原始计时器不会更改。只有新计时器受您在请求中发送的更新的影响。
请求示例：
请求
POST
https://countdownmail.com/api/duplicate/{code}
curl -H "Content-Type: application/json" \
-H "Authorization: YOUR_API_KEY" \
-X POST "https://countdownmail.com/api/duplicate/{code}" \
-d '{
"skin_id":6,
"name":"Flash Sale!",
"time_end":"2026-02-02 20:00:00"
}'
响应
{
"status": "success",
"message": {
"id": 1057,
"code": "td",
"src": "http://i.countdownmail.com/td.gif"
}
}
停用计时器
要停止计时器（存档），请向 /deactivate/{code} 发送 GET 请求。将 {code} 替换为计时器代码。
激活计时器
要再次激活计时器，请向 /activate/{code} 发送 GET 请求。将 {code} 替换为计时器代码。
删除计时器
要删除计时器，请向 /delete/{code} 发送 DELETE 请求。将 {code} 替换为计时器代码。
本指南应该为您提供开始使用 CountdownMail API 所需的一切。请妥善保管您的 API 密钥，并参阅官方文档了解有关时区或字体等字段的更多详细信息！
