2.0.0
OpenAPI 3.1.1

소개

이 문서는 스티비 API의 인증 방식, 공통 요청 규칙, 오류 응답 형식과 각 API의 요청 및 응답 구조를 설명합니다.

AI로 API 연동하기

AI 코딩 도구에 LLM용 문서 목차 주소를 전달하면 필요한 API별 문서를 참고할 수 있습니다. 전체 명세는 llms-full.txt에서 제공합니다.

사용 예시:

https://developers.stibee.com/llms.txt 를 읽고, 스티비 주소록에 구독자를 추가하는 코드를 작성해줘.

요금제별 권한

API 스탠다드 프로 엔터프라이즈
구독자 ✅ ✅ ✅
이메일, 그룹 - ✅ ✅
주소록, 발신자 주소 - - ✅
  • 구독자: 구독자 추가, 수정 등 구독자 관리를 자동화해 고객 DB와 연동할 수 있습니다.
  • 이메일, 그룹: 이메일 생성, 편집, 발송, 그룹 관리를 자동화할 수 있습니다.
  • 주소록, 발신자 주소: 주소록 관리와 발신자 이메일 주소 관리를 자동화할 수 있습니다.

요청 속도 제한

요청 속도 제한은 API 키가 속한 워크스페이스 단위로, 60초 고정 윈도우(fixed window) 방식으로 적용됩니다. 구간은 정각이 아니라 직전 구간이 끝난 뒤 첫 요청이 들어온 시점부터 60초이며, 60초가 지나면 횟수가 0으로 돌아갑니다. 429를 받은 요청도 횟수에 포함되지만 구간이 연장되지는 않습니다.

제한은 두 종류입니다.

  • 개별 제한: 아래 표의 네 API는 각자 횟수를 따로 셉니다. 예를 들어 구독자 목록 조회를 100회 호출해 제한에 걸려도 이메일 성과 조회나 그 외 API에는 영향이 없습니다.
  • 공유 제한: 네 API를 제외한 모든 API는 호출 횟수를 합산해 1000회/분으로 셉니다. 어떤 API를 호출했는지와 관계없이 같은 워크스페이스에서 나간 요청이면 모두 하나로 더해집니다.
API 엔드포인트 요청 속도 제한
구독자 대량 추가 POST /lists/{id}/subscribers/batch 최대 10회/분 (개별)
구독자 목록 조회 GET /lists/{id}/subscribers 최대 100회/분 (개별)
구독자 성과 조회 POST /lists/{id}/subscribers/stats/query 최대 100회/분 (개별)
이메일 성과 조회 GET /emails/stats 최대 100회/분 (개별)
그 외 모든 API 위 네 개를 제외한 전부 합산 최대 1000회/분 (공유)

예를 들어 이메일 상세 통계 조회(GET /emails/{id}/logs)를 1분에 1000회 호출하면, 같은 워크스페이스에서 보낸 구독자 추가·삭제 같은 다른 요청도 그 1분 동안 429로 거절됩니다.

제한을 초과하면 HTTP 429와 함께 Errors.Authorization.TooManyRequest가 반환됩니다. 429를 받으면 최대 60초 뒤에 다시 시도하고, 그래도 실패하면 간격을 점차 늘리세요. 주기적으로 호출하는 작업이 공유 제한을 꽉 채우면 같은 워크스페이스의 다른 요청이 함께 거절되므로, 다른 작업이 쓸 몫을 남겨 두고 설계하세요.

요금제별 권한, 요청 속도 제한은 각 API 항목별 페이지의 제목 위에 표시되어 있습니다.

Base URL

모든 API 요청은 다음 Base URL을 기준으로 합니다: https://api.stibee.com/v2

이메일 목록 조회 예시

GET https://api.stibee.com/v2/emails

인증

모든 API 요청에는 인증을 위해 AccessToken 헤더가 필요합니다. AccessToken은 스티비 서비스의 [워크스페이스 설정 > API 키]에서 생성할 수 있습니다. 자세한 내용은 스티비 도움말 > 주소록 API 사용하기 > API 키 만들기를 참고하세요.

2025년 1월 21일 이후에 생성된 API 키로만 인증할 수 있습니다. AccessToken 헤더가 없거나 유효하지 않으면 Errors.Authorization.NoToken (message: "존재하지 않는 토큰 입니다.") 오류가 반환됩니다.

인증 확인

/auth-check는 발급된 API 키를 사용해 인증이 정상적으로 되는지 확인할 수 있는 테스트용 요청입니다.

GET /auth-check
AccessToken: YOUR_API_KEY

오류 응답

요청이 성공하면 200 OK가 반환됩니다. 요청 값이 잘못되었거나 처리할 수 없는 경우 400 Bad Request가, 요청한 리소스를 찾을 수 없는 경우 404 Not Found가 반환됩니다. 요청 속도 제한을 초과한 경우에는 429 Too Many Requests와 함께 Errors.Authorization.TooManyRequest가 반환됩니다.

오류 응답 형식은 다음과 같습니다.

{
  "code":"Errors.Data.InvalidRequest",
  "httpStatusCode":400,
  "message":"잘못된 요청입니다."
}

분기 처리에는 code를 사용하세요. message는 사람이 읽기 위한 값이며 사전 고지 없이 바뀔 수 있습니다.

오류에 따라 values가 함께 반환됩니다. values.message는 무엇이 잘못되었는지 구체적으로 알려줍니다.

{
  "code":"Errors.Data.LimitExceeded",
  "httpStatusCode":400,
  "message":"요청 제한을 초과하였습니다.",
  "values":{"message":"이메일 목록 조회는 한 번에 최대 100건까지입니다."}
}

message에 {중괄호}가 있으면 서버가 치환하지 않고 그대로 보냅니다. 치환할 값은 values의 같은 이름 키에 담겨 옵니다.

{
  "code":"Errors.List.TooManyGroups",
  "httpStatusCode":400,
  "message":"그룹은 최대 {maxCount}개 까지만 만들 수 있습니다.",
  "values":{"maxCount":30}
}

일시적인 오류로 Errors.Service.TemporaryError 코드가 400과 함께 반환될 수 있습니다. 이 코드를 받으면 재시도 처리를 권장합니다.

5XX 응답도 일시적인 시스템 오류일 수 있습니다. 이 경우에도 재시도 처리를 권장합니다. 5XX는 위 오류 응답 형식을 따르지 않을 수 있습니다.

요청 형식

쿼리스트링을 제외한 모든 요청 본문은 application/json 형식이며, 인코딩은 UTF-8입니다.

Server:https://api.stibee.com/v2
Client Libraries