API에 대한 요청 및 응답 방법은 스티비 API 문서에서 확인하고 테스트해볼 수 있습니다.

API를 사용하면 스티비의 구독자 정보와 내 서비스의 사용자 정보를 연동하는 등 확장된 기능을 경험할 수 있습니다.


주소록 API는 주소록 웹훅과 함께 사용하면 더욱 강력한 기능이 됩니다 💪🏼

1. API 키 만들기

API를 사용하려면 우선 스티비에서 API 키를 만들어야 합니다. API는 계정 단위로 관리되기 때문에 API 키의 생성과 관리는 모두 사용자 메뉴의 계정 > API 키에서 이루어집니다.

2. API 사용하기

계정 > API 키에서 API 키를 생성한 뒤, API 키 옆의 복사하기를 클릭하면 API 키를 복사할 수 있습니다. 이 키는 API 요청 시 토큰으로 사용됩니다.

API 키가 노출되면 스티비 계정 보안에 치명적인 문제가 생길 수 있으니 주의하세요. 만약 노출이 의심되면 계정 > API 키에서 해당 키를 비활성화하거나 삭제하고 새로운 키를 만드세요.

API로 제공되는 기능은 다음과 같습니다.

  • 구독: 주소록에 구독자를 추가합니다.
  • 수신거부: 구독자를 수신거부 상태로 변경합니다.
  • 완전삭제: 구독자를 완전삭제합니다. 구독자 정보와 활동 기록이 모두 삭제됩니다. 삭제된 구독자 정보와 활동 기록은 복구할 수 없습니다.
  • 그룹 할당: 구독자를 주소록의 특정 그룹에 추가합니다. (2018년 9월 26일 업데이트)
  • 그룹 해제: 구독자를 주소록의 특정 그룹에서 삭제합니다. (2018년 9월 26일 업데이트)

(API로 제공되는 기능은 계속 추가될 예정입니다.)


API는 주소록 웹훅과 함께 활용하면 스티비의 주소록의 상태와 사용자 서버의 고객 정보를 동기화할 수 있습니다.

3. API 요청 및 응답 모델

API에 대한 요청 및 응답 방법은 스티비 API 문서에서 확인하고 테스트해볼 수 있습니다.

API 요청 및 응답은 JSON 형식을 따릅니다. 예를 들어, 주소록에 구독자를 추가하려면 POST Method로 다음과 같은 JSON 형식의 요청을 보냅니다.

* API 요청은 1초당 10회, 1회당 256KB로 제한되어 있습니다.

* 구독자 추가 시, 약 2,000명을 한 번에 추가할 수 있는 사이즈입니다. 사용자 정의 필드 값에 따라 다를 수 있습니다.

[공통]

Header

  • AccessToken: API 키
  • Content-Type: application/json

[구독]

HTTP Methods: POST

Endpoint URL: https://api.stibee.com/v1/lists/{listid}/subscribers

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

Request Body

  • eventOccuredBy: 구독자를 추가한 방법을 구분합니다.
    - "MANUAL": 관리자에 의해 추가한 것으로 기록합니다. (기본값)
    - "SUBSCRIBER": 구독자가 직접 구독한 것으로 기록합니다.
  • confirmEmailYN: 구독 확인 이메일 발송 여부를 구분합니다.
    - "Y": 구독자에게 구독 확인 이메일을 발송하고, 구독자가 이 메일을 통해 구독 확인을 해야 구독자로 추가됩니다. 이 때 한 번에 추가하는 구독자가 10명을 초과하면 추가되지 않습니다.
    - "N": 구독 확인 과정없이 바로 구독자로 추가됩니다. (기본값)
  • groupIds: 그룹에 할당된 고유의 아이디(groupId)입니다. 해당 그룹에 구독자를 할당하여 추가합니다. (기본값: 할당 안 함.)
  • subscribers: 구독자 정보를 담고 있습니다. Key-Value 배열 형식으로 구성됩니다. 주소록 > 사용자 정의 필드에 정의된 내용을 따릅니다.
    - Key: Key: 사용자 정의 필드의 "태그"(email, name 등)
    - Value: Key에 해당하는 값

추가 요청한 구독자가 주소록에 이미 존재하는 이메일 주소인 경우, eventOccuredBy 값과 구독자의 구독 상태에 따라 아래와 같이 처리됩니다.

  • eventOccuredBy가 MANUAL일 때: 이메일 주소, 이름 등의 구독자 정보를 업데이트합니다. 이 때 구독자의 구독 상태(예. 구독 중, 수신거부)는 변경되지 않습니다.
  • eventOccuredBy가 SUBSCRIBER일 때: 구독자의 구독 상태에 따라 다르게 처리됩니다.
    - 구독 중 상태일 때: 구독자 정보를 업데이트하지 않습니다. 기존 정보가 그대로 유지됩니다.
    - 수신거부 또는 자동삭제 상태일 때: 구독자의 구독 상태를 구독 중으로 변경하고 이메일 주소, 이름 등의 구독자 정보를 업데이트합니다.

주소록 웹훅으로 "구독" 이벤트 알림을 받기로 한 경우, "confirmEmailYN"이 "Y"라면, 구독 확인까지 완료됐을 때 이벤트 알림을 받을 수 있습니다.

groupId(그룹에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 "주소록 대시보드"로 이동
  • "그룹"을 클릭하여 그룹 목록으로 이동
  • 그룹 이름을 클릭하여 그룹 필터링이 적용된 구독자 목록으로 이동
  • 브라우저에 표시되는 URL에서 "subscribed" 뒤의 숫자를 확인

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.
    - code: 에러 코드
    - message: 에러 메세지
  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.
    - Key: 결과 유형
    - success: 구독자 추가 성공
    - update: 상태 외 정보 업데이트
    - failNoEmail: 구독자 추가 실패 - 이메일 주소 없음.
    - failExistEmail: 구독자 추가 실패 - 이미 구독 중인 이메일 주소
    - failExistPhone: 구독자 추가 실패 - 이미 구독 중인 전화번호
    - failWrongEmail: 구독자 추가 실패 - 이메일 주소 형식 오류
    - failWrongPhone: 구독자 추가 실패 - 전화번호 형식 오류
    - failDuplicatedEmail: 구독자 추가 실패 - 이메일 주소 중복 요청
    - failDuplicatedPhone: 구독자 추가 실패 - 전화번호 중복 요청
    - failUnknown: 구독자 추가 실패 - 알수 없는 오류
    - Value: Key에 해당하는 구독자 정보가 Key-Value 배열 형식으로 표시됩니다. [주소록] > [사용자 정의 필드]에 정의된 내용을 참조합니다.
    - Key: 사용자 정의 필드의 "태그"(email, name 등)
    - Value: Key에 해당하는 값

[완전삭제]

HTTP Methods: DELETE

Endpoint URL: https://api.stibee.com/v1/lists/{listid}/subscribers

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

Request Body

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.
  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.
    - "success": 구독자 완전삭제 성공 리스트
    - "fail": 구독자 완전삭제 실패 리스트

[수신거부]

HTTP Methods: PUT

Endpoint URL: https://api.stibee.com/v1/lists/{listid}/subscribers/unsubscribe

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

Request Body

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.
  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.
    - "success": 구독자 수신거부 성공 리스트
    - "failOrAlreadyUnsubscribe": 구독자 실패 또는 이미 수신거부 중 리스트

[그룹 할당]

HTTP Methods: POST

Endpoint URL: https://api.stibee.com/v1/lists/{listid}/groups/{groupId}/subscribers/assign

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

groupId(그룹에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 "주소록 대시보드"로 이동
  • "그룹"을 클릭하여 그룹 목록으로 이동
  • 그룹 이름을 클릭하여 그룹 필터링이 적용된 구독자 목록으로 이동
  • 브라우저에 표시되는 URL에서 "subscribed" 뒤의 숫자를 확인

Request Body

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.

[그룹 해제]

HTTP Methods: POST

Endpoint URL: https://api.stibee.com/v1/lists/{listid}/groups/{groupId}/subscribers/release

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

groupId(그룹에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 "주소록 대시보드"로 이동
  • "그룹"을 클릭하여 그룹 목록으로 이동
  • 그룹 이름을 클릭하여 그룹 필터링이 적용된 구독자 목록으로 이동
  • 브라우저에 표시되는 URL에서 "subscribed" 뒤의 숫자를 확인

Request Body

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.

API에 대한 요청 및 응답 방법은 스티비 API 문서에서 확인하고 테스트해볼 수 있습니다.

API 요청은 1초당 10회, 1회당 256KB로 제한되어 있습니다.

4. API 요청 및 응답 예제

gildong.go@stibee.com”, “dooly@stibee.com”을 구독 확인 과정 없이 추가할 경우, 다음과 같이 요청합니다.

POST https://api.stibee.com/v1/lists/{listId}/subscribers
[
    {
        "eventOccuredBy": "SUBSCRIBER",
        "confirmEmailYN": "N",
        "groupIds": [
         "{groupId}"
        ],
        "subscribers": [
            {
                "email": "gildong.go@stibee.com",
                "name": "고길동"
            },
            {
                "email": "dooly@stibee.com",
                "name": "둘리"
            }
        ]
    }
]

gildong.go@stibee.com”은 정상적으로 추가됐고, “dooly@stibee.com”은 수신거부 상태여서 추가되지 않았다면, 이에 대한 응답은 다음과 같습니다.

{
    "Ok": true,
    "Error": null,
    "Value": {
        "failDeny": [
                {
                        "email": "gildong.go@stibee.com",
                        "name": "고길동"
                }
        ],
        "failUnknown": [],
        "failWrongEmail": [],
        "success": [
                {
                        "email": "dooly@stibee.com",
                        "name": "둘리"
                }
        ],
        "update": []
    }
}

이미 추가된 "dooly@stibee.com"의 정보를 변경하려면, "eventOccuredBy"를 "MANUAL"로 설정하여, 다음과 같이 요청합니다.

POST https://api.stibee.com/v1/lists/{listId}/subscribers
[
    {
        "eventOccuredBy": "MANUAL",
        "confirmEmailYN": "N",
        "groupIds": [
         "{groupId}"
        ],
        "subscribers": [
            {
                "email": "dooly@stibee.com",
                "name": "둘리"
            }
        ]
    }
]

이미 추가된 구독자를 "eventOccuredBy"를 "SUBSCRIBER"로 설정하여 추가 요청하면 추가가 되지 않습니다. 이에 대한 응답은 다음과 같습니다.

{
    "Ok": false,
    "Error":
        {
            "Code": "LIST_ALREADY_SUBSCRIBED",
            "HttpStatusCode": 0,
            "Message": "이미 구독 중인 이메일 주소입니다."
        },
    "Value": null
}
답변을 찾으셨나요?