CountdownMail API

このガイドは、CountdownMail APIの使用開始を支援します。セットアップ、認証、エラー処理、カウントダウンタイマーの操作方法について説明します。

クイックスタート

このセクションでは、CountdownMail APIを使用する準備をし、最初のAPIリクエストの方法を示します。

  1. APIキーを取得:
    • CountdownMailアカウントにログインしてください。
    • プロフィール » APIに移動してください。
    • APIキーをコピーしてください。
  2. 最初の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コレクションをインポートしてください。 Postmanで実行
  • コレクションの認証設定にAPIキーを追加すれば、リクエストを開始する準備が整います。

エラー

APIリクエストが失敗することがあります。CountdownMail APIは、何が問題だったかを伝えるためにHTTPステータスコードを使用します。考えられるエラー、その意味、対処法のリストは次のとおりです:

コードステータス名説明推奨アクション
400不正なリクエストリクエストに問題があります。リクエストがドキュメントと一致し、正しい構文を使用しているか確認してください。
401未認証このリクエストを行う権限がありません。 Authorizationヘッダーで有効なAPIキーを使用していることを確認してください。
404見つかりませんサーバーはリクエストされたものを見つけられません。 URLが有効なAPIエンドポイントと一致しているか確認してください。
405メソッドが許可されていませんエンドポイントはそのメソッドをサポートしていません。 ドキュメントに示されている正しいHTTPメソッド（例：GET、POST）を使用してください。
429リクエストが多すぎますクライアントが1分間に多すぎるリクエストを送信しました。 各レスポンスで送信されるヘッダーを使用して、レート制限の現在のステータスを確認できます。
ヘッダー名説明
X-RateLimit-Limit1分あたりに行えるリクエストの最大数
X-RateLimit-Remaining現在のレート制限における残りのリクエスト数
X-RateLimit-Reset現在のレート制限がリセットされる時刻（UTCエポック秒）
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文字列メインカラー（16進コード）。はい例：FF3A43（赤）。
color_text文字列テキストカラー（16進コード）。はい例：FFFFFF（白）。
color_bg文字列背景色（16進コード）。はい例：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オブジェクト追加設定（例：区切り文字の色）。いいえ

例


{
    "separator_color"  : "4275BC",
    "separator_size" : 1.3,
    "separator_style" : 6,
    "labels_color" : "A3A3A3"
}

タイマーを作成

このエンドポイントでタイマーを作成できます。新しいタイマーを作成するには、すべての必須プロパティを指定する必要があります。

リクエスト例:

リクエスト

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"
    }
}

タイマーを更新

このエンドポイントでタイマーの任意の属性を更新できます。タイマーを更新するには、更新したいフィールドを含むPUTリクエストを/update/{code}に送信してください。{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キーを安全に保管し、タイムゾーンやフォントなどのフィールドの詳細については公式ドキュメントを参照してください！