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-Limit분당 최대 요청 수
X-RateLimit-Remaining현재 속도 제한에서 남은 요청 수
X-RateLimit-Reset현재 속도 제한이 재설정되는 시간 (UTC epoch 초)
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"
    }
}

타이머 업데이트

이 엔드포인트를 사용하여 타이머 속성을 업데이트할 수 있습니다. 타이머를 업데이트하려면 업데이트할 필드와 함께 /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 키를 안전하게 보관하고 시간대나 글꼴과 같은 필드에 대한 자세한 내용은 공식 문서를 참조하세요!