# 三竹簡訊 Python 函式庫
三竹簡訊 API 的 Python 包裝函式庫，讓您可以透過台灣三竹簡訊服務發送簡訊。
## 特色
- ✅ **預設 UTF-8 編碼**：完美支援中文簡訊，不會出現亂碼
- ✅ **單筆與批次發送**：支援單筆與批次簡訊發送
- ✅ **預約發送**：支援預約時間發送簡訊
- ✅ **狀態查詢**：查詢簡訊發送狀態與帳戶餘額
- ✅ **錯誤處理**：完整的錯誤處理機制
- ✅ **易於使用**：簡潔的 API 設計
## 安裝
```bash
pip install -e .
```
## 快速開始
### 基本設定
```python
from mitake import MitakeClient
# 方法 1：直接輸入帳號密碼
client = MitakeClient(username="your_username", password="your_password")
# 方法 2：使用環境變數
# 設定 MITAKE_USERNAME 和 MITAKE_PASSWORD 環境變數
client = MitakeClient()
```
### 發送單筆簡訊
```python
# 發送中文簡訊（自動使用 UTF-8 編碼，不會有亂碼問題）
result = client.send_sms(
to="0912345678", # 台灣手機號碼
message="你好，我是小海！這是測試訊息 🎉"
)
print(result)
```
### 發送批次簡訊
```python
messages = [
{"to": "0912345678", "message": "嗨！這是第一則訊息"},
{"to": "0987654321", "message": "嗨！這是第二則訊息", "message_id": "custom_id_1"},
{
"to": "0966666666",
"message": "這是完整參數的訊息",
"message_id": "full_example",
"send_time": "20241231235900", # YYYYMMDDHHMMSS 格式
"dest_name": "收訊人姓名"
}
]
result = client.send_batch_sms(messages)
print(result)
```
### 預約發送
```python
# 預約指定時間發送簡訊
result = client.send_sms(
to="0912345678",
message="這是預約發送的簡訊！",
send_time="2024-12-31 23:59:00" # YYYY-MM-DD HH:MM:SS 格式
)
```
### 查詢帳戶餘額
```python
balance = client.query_account_balance()
print(f"帳戶餘額：{balance}")
```
### 查詢簡訊狀態
```python
# 查詢已發送簡訊的狀態
status = client.query_message_status(["message_id_1", "message_id_2"])
print(status)
```
## 環境變數設定
您可以使用環境變數來設定認證資訊：
```bash
export MITAKE_USERNAME="你的帳號"
export MITAKE_PASSWORD="你的密碼"
```
## 錯誤處理
```python
from mitake import MitakeClient, MitakeError, AuthenticationError, APIError
try:
client = MitakeClient()
result = client.send_sms("0912345678", "測試訊息")
except AuthenticationError as e:
print(f"認證失敗：{e}")
except APIError as e:
print(f"API 錯誤：{e}")
print(f"狀態碼：{e.status_code}")
print(f"回應內容：{e.response_data}")
except MitakeError as e:
print(f"三竹簡訊錯誤：{e}")
```
## API 方法
### send_sms(to, message, message_id=None, send_time=None)
發送單筆簡訊
**參數：**
- `to` (str): 收訊人手機號碼（台灣格式：09xxxxxxxx）
- `message` (str): 簡訊內容
- `message_id` (str, 可選): 自訂訊息 ID
- `send_time` (str, 可選): 預約發送時間（YYYY-MM-DD HH:MM:SS 格式）
### send_batch_sms(messages)
發送批次簡訊
**參數：**
- `messages` (List[Dict]): 訊息列表，每個訊息包含：
- `to` (str): 收訊人手機號碼（必填）
- `message` (str): 簡訊內容（必填）
- `message_id` (str, 可選): 自訂訊息 ID
- `send_time` (str, 可選): 預約發送時間（YYYYMMDDHHMMSS 格式）
- `valid_time` (str, 可選): 訊息有效時間（YYYYMMDDHHMMSS 格式）
- `dest_name` (str, 可選): 收訊人姓名
- `callback_url` (str, 可選): 狀態回報網址
### query_account_balance()
查詢帳戶餘額
### query_message_status(message_ids)
查詢簡訊發送狀態
**參數：**
- `message_ids` (List[str]): 要查詢的訊息 ID 列表
## UTF-8 編碼支援
本函式庫預設使用 UTF-8 編碼，完美支援中文簡訊：
```python
# ✅ 正確：支援中文、表情符號等
client.send_sms("0912345678", "你好！今天天氣真好 ☀️")
# ✅ 正確：支援各種特殊字元
client.send_sms("0912345678", "測試特殊符號：{} [] | ^ ~ 等等")
```
## 系統需求
- Python 3.7+
- requests 函式庫
## 授權條款
MIT License
## 開發者
使用前請確保您已向三竹資訊申請 API 發送權限，並提供程式發送主機的 IP 位址進行鎖定。
更多 API 詳細資訊請參考：[三竹簡訊 API 文件](HTTP_MitakeAPI_v2.14.pdf)
Raw data
{
"_id": null,
"home_page": "https://github.com/tzangms/mitake",
"name": "mitake",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mitake sms api taiwan",
"author": "tzangms",
"author_email": "tzangms@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/96/c0/89704d66586066b6af8ea7011aaccf324d462ff26476a7f11d3c6c54d996/mitake-0.9.2.tar.gz",
"platform": null,
"description": "# \u4e09\u7af9\u7c21\u8a0a Python \u51fd\u5f0f\u5eab\n\n\u4e09\u7af9\u7c21\u8a0a API \u7684 Python \u5305\u88dd\u51fd\u5f0f\u5eab\uff0c\u8b93\u60a8\u53ef\u4ee5\u900f\u904e\u53f0\u7063\u4e09\u7af9\u7c21\u8a0a\u670d\u52d9\u767c\u9001\u7c21\u8a0a\u3002\n\n## \u7279\u8272\n\n- \u2705 **\u9810\u8a2d UTF-8 \u7de8\u78bc**\uff1a\u5b8c\u7f8e\u652f\u63f4\u4e2d\u6587\u7c21\u8a0a\uff0c\u4e0d\u6703\u51fa\u73fe\u4e82\u78bc\n- \u2705 **\u55ae\u7b46\u8207\u6279\u6b21\u767c\u9001**\uff1a\u652f\u63f4\u55ae\u7b46\u8207\u6279\u6b21\u7c21\u8a0a\u767c\u9001\n- \u2705 **\u9810\u7d04\u767c\u9001**\uff1a\u652f\u63f4\u9810\u7d04\u6642\u9593\u767c\u9001\u7c21\u8a0a\n- \u2705 **\u72c0\u614b\u67e5\u8a62**\uff1a\u67e5\u8a62\u7c21\u8a0a\u767c\u9001\u72c0\u614b\u8207\u5e33\u6236\u9918\u984d\n- \u2705 **\u932f\u8aa4\u8655\u7406**\uff1a\u5b8c\u6574\u7684\u932f\u8aa4\u8655\u7406\u6a5f\u5236\n- \u2705 **\u6613\u65bc\u4f7f\u7528**\uff1a\u7c21\u6f54\u7684 API \u8a2d\u8a08\n\n## \u5b89\u88dd\n\n```bash\npip install -e .\n```\n\n## \u5feb\u901f\u958b\u59cb\n\n### \u57fa\u672c\u8a2d\u5b9a\n\n```python\nfrom mitake import MitakeClient\n\n# \u65b9\u6cd5 1\uff1a\u76f4\u63a5\u8f38\u5165\u5e33\u865f\u5bc6\u78bc\nclient = MitakeClient(username=\"your_username\", password=\"your_password\")\n\n# \u65b9\u6cd5 2\uff1a\u4f7f\u7528\u74b0\u5883\u8b8a\u6578\n# \u8a2d\u5b9a MITAKE_USERNAME \u548c MITAKE_PASSWORD \u74b0\u5883\u8b8a\u6578\nclient = MitakeClient()\n```\n\n### \u767c\u9001\u55ae\u7b46\u7c21\u8a0a\n\n```python\n# \u767c\u9001\u4e2d\u6587\u7c21\u8a0a\uff08\u81ea\u52d5\u4f7f\u7528 UTF-8 \u7de8\u78bc\uff0c\u4e0d\u6703\u6709\u4e82\u78bc\u554f\u984c\uff09\nresult = client.send_sms(\n to=\"0912345678\", # \u53f0\u7063\u624b\u6a5f\u865f\u78bc\n message=\"\u4f60\u597d\uff0c\u6211\u662f\u5c0f\u6d77\uff01\u9019\u662f\u6e2c\u8a66\u8a0a\u606f \ud83c\udf89\"\n)\nprint(result)\n```\n\n### \u767c\u9001\u6279\u6b21\u7c21\u8a0a\n\n```python\nmessages = [\n {\"to\": \"0912345678\", \"message\": \"\u55e8\uff01\u9019\u662f\u7b2c\u4e00\u5247\u8a0a\u606f\"},\n {\"to\": \"0987654321\", \"message\": \"\u55e8\uff01\u9019\u662f\u7b2c\u4e8c\u5247\u8a0a\u606f\", \"message_id\": \"custom_id_1\"},\n {\n \"to\": \"0966666666\", \n \"message\": \"\u9019\u662f\u5b8c\u6574\u53c3\u6578\u7684\u8a0a\u606f\",\n \"message_id\": \"full_example\",\n \"send_time\": \"20241231235900\", # YYYYMMDDHHMMSS \u683c\u5f0f\n \"dest_name\": \"\u6536\u8a0a\u4eba\u59d3\u540d\"\n }\n]\n\nresult = client.send_batch_sms(messages)\nprint(result)\n```\n\n### \u9810\u7d04\u767c\u9001\n\n```python\n# \u9810\u7d04\u6307\u5b9a\u6642\u9593\u767c\u9001\u7c21\u8a0a\nresult = client.send_sms(\n to=\"0912345678\",\n message=\"\u9019\u662f\u9810\u7d04\u767c\u9001\u7684\u7c21\u8a0a\uff01\",\n send_time=\"2024-12-31 23:59:00\" # YYYY-MM-DD HH:MM:SS \u683c\u5f0f\n)\n```\n\n### \u67e5\u8a62\u5e33\u6236\u9918\u984d\n\n```python\nbalance = client.query_account_balance()\nprint(f\"\u5e33\u6236\u9918\u984d\uff1a{balance}\")\n```\n\n### \u67e5\u8a62\u7c21\u8a0a\u72c0\u614b\n\n```python\n# \u67e5\u8a62\u5df2\u767c\u9001\u7c21\u8a0a\u7684\u72c0\u614b\nstatus = client.query_message_status([\"message_id_1\", \"message_id_2\"])\nprint(status)\n```\n\n## \u74b0\u5883\u8b8a\u6578\u8a2d\u5b9a\n\n\u60a8\u53ef\u4ee5\u4f7f\u7528\u74b0\u5883\u8b8a\u6578\u4f86\u8a2d\u5b9a\u8a8d\u8b49\u8cc7\u8a0a\uff1a\n\n```bash\nexport MITAKE_USERNAME=\"\u4f60\u7684\u5e33\u865f\"\nexport MITAKE_PASSWORD=\"\u4f60\u7684\u5bc6\u78bc\"\n```\n\n## \u932f\u8aa4\u8655\u7406\n\n```python\nfrom mitake import MitakeClient, MitakeError, AuthenticationError, APIError\n\ntry:\n client = MitakeClient()\n result = client.send_sms(\"0912345678\", \"\u6e2c\u8a66\u8a0a\u606f\")\nexcept AuthenticationError as e:\n print(f\"\u8a8d\u8b49\u5931\u6557\uff1a{e}\")\nexcept APIError as e:\n print(f\"API \u932f\u8aa4\uff1a{e}\")\n print(f\"\u72c0\u614b\u78bc\uff1a{e.status_code}\")\n print(f\"\u56de\u61c9\u5167\u5bb9\uff1a{e.response_data}\")\nexcept MitakeError as e:\n print(f\"\u4e09\u7af9\u7c21\u8a0a\u932f\u8aa4\uff1a{e}\")\n```\n\n## API \u65b9\u6cd5\n\n### send_sms(to, message, message_id=None, send_time=None)\n\u767c\u9001\u55ae\u7b46\u7c21\u8a0a\n\n**\u53c3\u6578\uff1a**\n- `to` (str): \u6536\u8a0a\u4eba\u624b\u6a5f\u865f\u78bc\uff08\u53f0\u7063\u683c\u5f0f\uff1a09xxxxxxxx\uff09\n- `message` (str): \u7c21\u8a0a\u5167\u5bb9\n- `message_id` (str, \u53ef\u9078): \u81ea\u8a02\u8a0a\u606f ID\n- `send_time` (str, \u53ef\u9078): \u9810\u7d04\u767c\u9001\u6642\u9593\uff08YYYY-MM-DD HH:MM:SS \u683c\u5f0f\uff09\n\n### send_batch_sms(messages)\n\u767c\u9001\u6279\u6b21\u7c21\u8a0a\n\n**\u53c3\u6578\uff1a**\n- `messages` (List[Dict]): \u8a0a\u606f\u5217\u8868\uff0c\u6bcf\u500b\u8a0a\u606f\u5305\u542b\uff1a\n - `to` (str): \u6536\u8a0a\u4eba\u624b\u6a5f\u865f\u78bc\uff08\u5fc5\u586b\uff09\n - `message` (str): \u7c21\u8a0a\u5167\u5bb9\uff08\u5fc5\u586b\uff09\n - `message_id` (str, \u53ef\u9078): \u81ea\u8a02\u8a0a\u606f ID\n - `send_time` (str, \u53ef\u9078): \u9810\u7d04\u767c\u9001\u6642\u9593\uff08YYYYMMDDHHMMSS \u683c\u5f0f\uff09\n - `valid_time` (str, \u53ef\u9078): \u8a0a\u606f\u6709\u6548\u6642\u9593\uff08YYYYMMDDHHMMSS \u683c\u5f0f\uff09\n - `dest_name` (str, \u53ef\u9078): \u6536\u8a0a\u4eba\u59d3\u540d\n - `callback_url` (str, \u53ef\u9078): \u72c0\u614b\u56de\u5831\u7db2\u5740\n\n### query_account_balance()\n\u67e5\u8a62\u5e33\u6236\u9918\u984d\n\n### query_message_status(message_ids)\n\u67e5\u8a62\u7c21\u8a0a\u767c\u9001\u72c0\u614b\n\n**\u53c3\u6578\uff1a**\n- `message_ids` (List[str]): \u8981\u67e5\u8a62\u7684\u8a0a\u606f ID \u5217\u8868\n\n## UTF-8 \u7de8\u78bc\u652f\u63f4\n\n\u672c\u51fd\u5f0f\u5eab\u9810\u8a2d\u4f7f\u7528 UTF-8 \u7de8\u78bc\uff0c\u5b8c\u7f8e\u652f\u63f4\u4e2d\u6587\u7c21\u8a0a\uff1a\n\n```python\n# \u2705 \u6b63\u78ba\uff1a\u652f\u63f4\u4e2d\u6587\u3001\u8868\u60c5\u7b26\u865f\u7b49\nclient.send_sms(\"0912345678\", \"\u4f60\u597d\uff01\u4eca\u5929\u5929\u6c23\u771f\u597d \u2600\ufe0f\")\n\n# \u2705 \u6b63\u78ba\uff1a\u652f\u63f4\u5404\u7a2e\u7279\u6b8a\u5b57\u5143\nclient.send_sms(\"0912345678\", \"\u6e2c\u8a66\u7279\u6b8a\u7b26\u865f\uff1a{} [] | ^ ~ \u7b49\u7b49\")\n```\n\n## \u7cfb\u7d71\u9700\u6c42\n\n- Python 3.7+\n- requests \u51fd\u5f0f\u5eab\n\n## \u6388\u6b0a\u689d\u6b3e\n\nMIT License\n\n## \u958b\u767c\u8005\n\n\u4f7f\u7528\u524d\u8acb\u78ba\u4fdd\u60a8\u5df2\u5411\u4e09\u7af9\u8cc7\u8a0a\u7533\u8acb API \u767c\u9001\u6b0a\u9650\uff0c\u4e26\u63d0\u4f9b\u7a0b\u5f0f\u767c\u9001\u4e3b\u6a5f\u7684 IP \u4f4d\u5740\u9032\u884c\u9396\u5b9a\u3002\n\n\u66f4\u591a API \u8a73\u7d30\u8cc7\u8a0a\u8acb\u53c3\u8003\uff1a[\u4e09\u7af9\u7c21\u8a0a API \u6587\u4ef6](HTTP_MitakeAPI_v2.14.pdf)\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library for Mitake SMS API",
"version": "0.9.2",
"project_urls": {
"Bug Reports": "https://github.com/tzangms/mitake/issues",
"Homepage": "https://github.com/tzangms/mitake",
"Source": "https://github.com/tzangms/mitake"
},
"split_keywords": [
"mitake",
"sms",
"api",
"taiwan"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cd3343d80db8e098364376c44258f61807e74901e1a58114f14af9b5e1ff418b",
"md5": "96e4617e47b4a40fb7a3e880e1b8d163",
"sha256": "f0db6cfd0cfcf5bc3ed3a63124a316696b9ad986dc0a63fae50979088b69d04c"
},
"downloads": -1,
"filename": "mitake-0.9.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96e4617e47b4a40fb7a3e880e1b8d163",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15160,
"upload_time": "2025-08-20T02:42:54",
"upload_time_iso_8601": "2025-08-20T02:42:54.331356Z",
"url": "https://files.pythonhosted.org/packages/cd/33/43d80db8e098364376c44258f61807e74901e1a58114f14af9b5e1ff418b/mitake-0.9.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "96c089704d66586066b6af8ea7011aaccf324d462ff26476a7f11d3c6c54d996",
"md5": "9bbc5408bbbde93e04fa36022b661a84",
"sha256": "a4058810eb6a8b68aa520a893ac8912e31a76415a5993de66f325d29a58703cf"
},
"downloads": -1,
"filename": "mitake-0.9.2.tar.gz",
"has_sig": false,
"md5_digest": "9bbc5408bbbde93e04fa36022b661a84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11401,
"upload_time": "2025-08-20T02:42:56",
"upload_time_iso_8601": "2025-08-20T02:42:56.607335Z",
"url": "https://files.pythonhosted.org/packages/96/c0/89704d66586066b6af8ea7011aaccf324d462ff26476a7f11d3c6c54d996/mitake-0.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 02:42:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tzangms",
"github_project": "mitake",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
}
],
"lcname": "mitake"
}
JSON
