스티비 API
소개
이 문서는 스티비 API의 인증 방식, 공통 요청 규칙, 오류 응답 형식과 각 API의 요청 및 응답 구조를 설명합니다.
AI로 API 연동하기
AI 코딩 도구에 LLM용 문서 목차 주소를 전달하면 필요한 API별 문서를 참고할 수 있습니다. 전체 명세는 llms-full.txt에서 제공합니다.
사용 예시:
https://developers.stibee.com/llms.txt 를 읽고, 스티비 주소록에 구독자를 추가하는 코드를 작성해줘.
요금제별 권한
요청 속도 제한
요청 속도 제한은 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입니다.

