API キー管理
API キーは Zeabur Email API リクエストの認証に使用されます。各キーには異なる権限レベルを設定できます。
権限タイプ
Zeabur Email は3つの権限レベルを提供します：
| 権限タイプ | 説明 | 使用例 |
|---|---|---|
読み取り専用 (read_only) | メールと統計情報のクエリのみ可能 | データ分析、監視ダッシュボード |
送信専用 (send_only) | メール送信とステータスクエリが可能 | 本番環境アプリケーション（推奨） |
全権限 (all) | すべての操作権限を含む | 管理ツール、開発環境 |
セキュリティ上の理由から、本番環境では「送信専用」権限を使用し、「全権限」の使用を避けることをお勧めします。
API キーの作成
コンソールにログイン
Zeabur コンソールの Zeabur Email 管理ページにアクセスします。
新しいキーを作成
- 「API キー管理」に移動
- 「API キーを作成」をクリック
- キー名を入力（識別用）
- 権限タイプを選択
- （オプション）特定のドメインに制限
- 「作成」をクリック
キーを保存
キーは作成時に一度だけ表示されます！すぐに安全な場所に保存してください。
作成後、システムは完全な API キーを表示します。コピーして安全に保存してください。再度表示することはできません。
ドメイン制限
セキュリティを強化するため、API キーを特定のドメインからのメール送信のみに制限できます：
// キー作成時に許可されたドメインを設定
{
"name": "Production API Key",
"permission": "send_only",
"allowed_domains": ["yourdomain.com", "mail.yourdomain.com"]
}これにより、キーが漏洩しても、攻撃者は未承認のドメインを使用してメールを送信できません。
API キーの使用
HTTP リクエストヘッダー
すべての API リクエストにキーを含めます：
POST /api/v1/zsend/emails
Host: api.zeabur.com
Content-Type: application/json
Authorization: Bearer zs_your_api_key_here
{
"from": "[email protected]",
...
}コード例
JavaScript
const apiKey = process.env.ZSEND_API_KEY;
const response = await fetch('https://api.zeabur.com/api/v1/zsend/emails', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + apiKey
},
body: JSON.stringify({
from: '[email protected]',
to: ['[email protected]'],
subject: 'テストメール',
html: '<p>テスト内容</p>'
})
});Python
import os
import requests
api_key = os.environ.get('ZSEND_API_KEY')
response = requests.post(
'https://api.zeabur.com/api/v1/zsend/emails',
headers={
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + api_key
},
json={
'from': '[email protected]',
'to': ['[email protected]'],
'subject': 'テストメール',
'html': '<p>テスト内容</p>'
}
)Go
package main
import (
"bytes"
"encoding/json"
"net/http"
"os"
)
func sendEmail() error {
apiKey := os.Getenv("ZSEND_API_KEY")
payload := map[string]interface{}{
"from": "[email protected]",
"to": []string{"[email protected]"},
"subject": "テストメール",
"html": "<p>テスト内容</p>",
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", "https://api.zeabur.com/api/v1/zsend/emails", bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer " + apiKey)
client := &http.Client{}
resp, err := client.Do(req)
return err
}キーのローテーション
定期的な API キーのローテーションは良いセキュリティ慣行です：
新しいキーを作成
古いキーをアクティブに保ちながら、新しい API キーを作成します。
アプリケーション設定を更新
アプリケーションの API キーを新しいキーに段階的に更新します。
古いキーを削除
すべてのアプリケーションが更新されたことを確認した後、古いキーを削除します。
90日ごとにキーをローテーションすることをお勧めします。
キーの取り消し
キーが漏洩した場合、または不要になった場合：
- 「API キー管理」に移動
- 削除するキーを見つける
- 「削除」ボタンをクリック
- 削除を確認
キーを削除すると、そのキーを使用するすべての API リクエストは直ちに失敗します。
セキュリティのベストプラクティス
1. 環境変数を使用
コードに API キーをハードコーディングしないでください：
// ❌ 推奨されません：ハードコーディングしない
const apiKey = 'zs_xxxxxxxxxxxxxxxxxxxxxxxx';
// ✅ 推奨：環境変数を使用
const apiKey = process.env.ZSEND_API_KEY;2. 最小権限の原則を使用
異なるアプリケーション用に適切な権限を持つ個別のキーを作成します：
- 本番アプリケーション：送信専用権限 + ドメイン制限
- データ分析：読み取り専用権限
- 管理ツール：全権限（必要な場合のみ）
3. キーの使用状況を監視
Zeabur Email コンソールで各キーの使用統計を表示します：
- リクエスト数
- 送信メール数
- エラー率
異常な使用が検出された場合は、直ちにキーを取り消します。
4. キーを共有しない
各アプリケーションと環境（開発/本番）用に個別のキーを作成し、追跡と管理を容易にします。
トラブルシューティング
401 Unauthorized
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}考えられる原因：
- API キーが正しくない、または削除されている
- リクエストヘッダーの形式が間違っている（
Authorization: Bearer <token>である必要があります） - キーに先頭/末尾のスペースがある、または
Bearerプレフィックスがない
403 Forbidden
{
"error": "permission denied",
"message": "API key does not have permission to send from this domain"
}考えられる原因：
- キーの権限が不十分（例：読み取り専用キーでメールを送信）
- 送信者ドメインがキーの許可リストにない
- ドメインが検証されていない
429 Too Many Requests
{
"error": "too many requests",
"message": "Rate limit exceeded"
}解決策：
- リクエストのスロットリングとリトライメカニズムを実装
- より高いレート制限のためにアカウントのアップグレードを検討
- バッチ送信 API を使用してリクエスト数を削減